www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Any ddox experts n da house?

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Hello,


I'm chatting with Vladimir on IRC and we reached the conclusion that 
neither of us has the expertise to maintain the ddox-based build, nor 
the bandwidth to get into it.

Is there someone who can help us with improving our ddox-based Phobos 
documentation build? There are several issues with it of varying 
gravity, nothing fundamental but a good chunk of work.

Counting on your help!


Thanks,

Andrei
Feb 14 2015
parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Saturday, 14 February 2015 at 09:17:57 UTC, Andrei 
Alexandrescu wrote:
 Counting on your help!
Here are some things that would help: 1. Most urgently, update the .dt template to match the current Dlang.org style. 2. Ideally, the .dt templates need to be removed, and DDox made to use the existing DDoc templates. This is so future website updates are immediately reflected in DDox, to avoid this situation in the future. 3. Currently, DDox creates all .html files regardless if they've actually changed or not, thus making each generated file always have a new modification time. Because the website is uploaded via rsync, this greatly increases upload time. This can be solved by making DDox first create a Makefile include, or by simply making it not overwrite files with identical content. There is generally something very broken about the DDox templates. I've attempted to fix the website by adding a copy of the old style.css, and I've modified layout.dt like so: diff --git a/dpl-docs/views/layout.dt b/dpl-docs/views/layout.dt index c4ddcb0..2960625 100644 --- a/dpl-docs/views/layout.dt +++ b/dpl-docs/views/layout.dt -19,7 +19,7 html(lang='en-US') script(src='#{root_dir}js/d.js') script(src='#{root_dir}js/run.js', type='text/javascript') link(rel='stylesheet', href='#{root_dir}css/codemirror.css') - link(rel='stylesheet', type='text/css', href='#{root_dir}css/style.css') + link(rel='stylesheet', type='text/css', href='#{root_dir}css/style-2014.css') script(src='#{root_dir}js/hyphenate-selectively.js', type='text/javascript') script(type="text/javascript", src="#{root_dir}prettify/prettify.js") Yet, no matter what I do, which files I delete or how I attempt to rebuild, the generated .html files still reference "style.css" and not "style-2014.css". I'm also getting strange linker errors when attempting to rebuild DDox: http://dump.thecybershadow.net/e6c93daabcbe9b01be9414d8d63913d8/0000009F.txt These only happen SOMETIMES. They don't happen on a clean build. I haven't identified the pattern, but it seems to vary between working and not working without me changing anything in the environment.
Feb 14 2015
next sibling parent reply Mathias Lang via Digitalmars-d <digitalmars-d puremagic.com> writes:
2015-02-14 10:46 GMT+01:00 Vladimir Panteleev via Digitalmars-d <
digitalmars-d puremagic.com>:

 On Saturday, 14 February 2015 at 09:17:57 UTC, Andrei Alexandrescu wrote:

 Counting on your help!
Here are some things that would help: 1. Most urgently, update the .dt template to match the current Dlang.org style. 2. Ideally, the .dt templates need to be removed, and DDox made to use the existing DDoc templates. This is so future website updates are immediately reflected in DDox, to avoid this situation in the future.
I'm leaning in the other direction: the website should not be based on a macro processing system, but rather on a web framework. However, we use the *content* on dlang.org to generate other targets than the website. It would be unacceptable to kill these targets just to switch to another framework, so there's a compromise to find here. Relevant link: http://forum.dlang.org/thread/m9g1kt$1j01$1 digitalmars.com Right now all the boilerplate of the website (navigation, basic layout) lies within the 'DDOC' macros, in which every file gets inserted. On the long run I plan to switch this to a Diet template, so ddox and the website will share it and it will reduce the maintenance burden. The format of the content itself will not change, it will still be in ".dd" files, and they will get processed by the site on startup. We'll get the best of both world, keeping the possibility to output any target out of the specs, but writting website-specific part in a proper framework. I've got a PoC working, which generate exactly the same layout as dlang.org (give or take a few whitespaces), but is based on Vibe.d: http://doc.mimiks.net:8000/changelog.html . Once it's polished, I'll P.R.
Feb 14 2015
parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Saturday, 14 February 2015 at 23:06:20 UTC, Mathias Lang wrote:
 We'll get the best of both
 world, keeping the possibility to output any target out of the 
 specs, but
 writting website-specific part in a proper framework.
And the advantages of this are..? Sorry, but I don't think this is going to fly. You are proposing switching parts of the the website to Diet templates. This is one more DSL that contributors will need to know. We will have two different macro systems for building one website, and a ton of dependencies to boot. Furthermore, this is probably the worst possible moment for such a proposal - you are suggesting that we move even more weight on something that is, right now, not merely unmaintained, but broken, and with no one wanting to fix it. Even if you complete your work, and assuming it gets accepted, who is going to maintain it? Right now, it would take a very strong argument to prove that we need to migrate MORE parts to Vibe when the existing ones barely hold up.
Feb 14 2015
next sibling parent "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Saturday, 14 February 2015 at 23:38:38 UTC, Vladimir Panteleev 
wrote:
 On Saturday, 14 February 2015 at 23:06:20 UTC, Mathias Lang 
 wrote:
 We'll get the best of both
 world, keeping the possibility to output any target out of the 
 specs, but
 writting website-specific part in a proper framework.
And the advantages of this are..?
Another thing. I'm planning to make the forum and wiki use the Dlang.org theme - and not a copy, which will quickly become outdated, but actually use DDoc so that these websites will get updates automatically. This would be simple with DDoc, only a matter of splitting and refactoring a few macros here and there. How would this fit in your proposal?
Feb 14 2015
prev sibling parent Mathias Lang via Digitalmars-d <digitalmars-d puremagic.com> writes:
2015-02-15 0:38 GMT+01:00 Vladimir Panteleev via Digitalmars-d <
digitalmars-d puremagic.com>:

 On Saturday, 14 February 2015 at 23:06:20 UTC, Mathias Lang wrote:

 We'll get the best of both
 world, keeping the possibility to output any target out of the specs, but
 writting website-specific part in a proper framework.
And the advantages of this are..? Sorry, but I don't think this is going to fly. You are proposing switching parts of the the website to Diet templates. This is one more DSL that contributors will need to know. We will have two different macro systems for building one website, and a ton of dependencies to boot. Furthermore, this is probably the worst possible moment for such a proposal - you are suggesting that we move even more weight on something that is, right now, not merely unmaintained, but broken, and with no one wanting to fix it. Even if you complete your work, and assuming it gets accepted, who is going to maintain it? Right now, it would take a very strong argument to prove that we need to migrate MORE parts to Vibe when the existing ones barely hold up.
One of the point of the vision document was to emphasize Vibe.d, and I'm trying to do just that. The advantages, from the top of my head, are: - Dogfooding: we have a web framework, and we're using it for our website. What message does it send ? - Simplified build process: on the long run we'll be able to reduce, if not ditch, the makefiles, and get the site up and running with a simple command, no matter what platform you're on. - Feedback on both Vibe.d and dub. - More capabilities in the website: currently, anything dynamic has to be done as a separate part (i.e. the forums), or in php (bugstats). In the future such work could be integrated directly into the website. It could also be made more dynamic, which opens a lot of possibilities, from simple improvement (detecting the user's system and pushing the proper download link to the top of the list), to more advanced one (providing Martin Nowak's REPL, or better downloads / site consultation information). A good point with this proposal is that it's not distruptive to the existent: DDOC allows us to make this change smoothly, so if the change gets pulled, it won't change anything to you, or anyone else that doesn't want to use it. I expect some resistance, but I believe using it will be the best way to prove it's usefulness.
Feb 15 2015
prev sibling parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig rejectedsoftware.com> writes:
Am 14.02.2015 um 10:46 schrieb Vladimir Panteleev:
 On Saturday, 14 February 2015 at 09:17:57 UTC, Andrei Alexandrescu wrote:
 Counting on your help!
Here are some things that would help: 1. Most urgently, update the .dt template to match the current Dlang.org style.
I've done that quickly (using a HTML to Jade converter). Will open a pull request soon.
 2. Ideally, the .dt templates need to be removed, and DDox made to use
 the existing DDoc templates. This is so future website updates are
 immediately reflected in DDox, to avoid this situation in the future.
This should be doable one way or another, it just probably requires some hacks, because Ddoc works top-down, while the Diet templates are processed bottom-up.
 3. Currently, DDox creates all .html files regardless if they've
 actually changed or not, thus making each generated file always have a
 new modification time. Because the website is uploaded via rsync, this
 greatly increases upload time. This can be solved by making DDox first
 create a Makefile include, or by simply making it not overwrite files
 with identical content.
I'll look into that. https://github.com/rejectedsoftware/ddox/issues/73
 There is generally something very broken about the DDox templates. I've
 attempted to fix the website by adding a copy of the old style.css, and
 I've modified layout.dt like so:

 diff --git a/dpl-docs/views/layout.dt b/dpl-docs/views/layout.dt
 index c4ddcb0..2960625 100644
 --- a/dpl-docs/views/layout.dt
 +++ b/dpl-docs/views/layout.dt
    -19,7 +19,7    html(lang='en-US')
       script(src='#{root_dir}js/d.js')
       script(src='#{root_dir}js/run.js', type='text/javascript')
       link(rel='stylesheet', href='#{root_dir}css/codemirror.css')
 -    link(rel='stylesheet', type='text/css',
 href='#{root_dir}css/style.css')
 +    link(rel='stylesheet', type='text/css',
 href='#{root_dir}css/style-2014.css')
       script(src='#{root_dir}js/hyphenate-selectively.js',
 type='text/javascript')

       script(type="text/javascript", src="#{root_dir}prettify/prettify.js")

 Yet, no matter what I do, which files I delete or how I attempt to
 rebuild, the generated .html files still reference "style.css" and not
 "style-2014.css".
This is a known bug that I had completely forgotten about. It needs to get a priority boost. https://github.com/D-Programming-Language/dub/issues/331
 I'm also getting strange linker errors when attempting to rebuild DDox:

 http://dump.thecybershadow.net/e6c93daabcbe9b01be9414d8d63913d8/0000009F.txt


 These only happen SOMETIMES. They don't happen on a clean build. I
 haven't identified the pattern, but it seems to vary between working and
 not working without me changing anything in the environment.
No idea what could cause this. Does running DUB with --build-mode=allAtOnce help (performs compile and link with a single DMD invocation)?
Feb 15 2015