search

JakobOvrum / bootDoc

Theme for the DDoc documentation generator
Other
36 stars 7 forks source link

Markdown export? #31

Closed nikibobi closed 11 years ago

nikibobi commented 11 years ago

@JakobOvrum, I haven't used bootDoc yet, but I am quite impressed with the phobos demo. I was wondering if it is possible to generate markdown instead of pure html? Like one .md file per module that lists everything. This will be great for smaller code bases that don't need a whole website(or gh-pages branch) and can just place a README.md file in the module's folder.

Also does bootDoc use DDoc or is it completely separate from DDoc?

JakobOvrum commented 11 years ago

bootDoc is a DDoc template. See bootdoc.ddoc for the main macro - which is called DDOC - as well as other macro definitions (see the DDoc documentation for a list of specially recognized macros and what they all mean). It uses Bootstrap's CSS and JavaScript for styling, as well as some custom JavaScript (in bootdoc.js) to make up for some of DDoc's many inherent limitations. The generate.d script is a relatively simple helper tool that in turn calls the D compiler to do most of the work.

Hence, bootDoc is very closely coupled with DDoc and apart from the overall styling, is of no use without DDoc.

bootDoc as a template for DDoc is HTML, which, when coupled with the supporting CSS, JavaScript and the simple helper tool, makes up the entirety of the bootDoc project. There is virtually no room for reuse here if one wanted to output Markdown.

DDoc is theoretically not limited to any particular markup language and it is possible to write a template that uses Markdown. However, DDoc on its own is rather lackluster which is why bootDoc uses JavaScript to cover up some of the most glaring problems. With Markdown, that's not an option, so it's probably better to forego DDoc in favour of a tool that generates documentation based on the JSON-formatted metadata that the compiler can output (see the -X and -Xf flags to DMD). IIRC, the JSON output has improved a lot in recent releases (been interested in working on such a tool myself). I'm not very familiar with it, but I think ddox is one such project.

I really like Markdown myself and I think it would be neat to have a nice, solid tool that can generate Markdown documentation from D sources (ideally using the same documentation comment syntax as DDoc). Github wiki pages also accept markdown, so that's another option for hosting them.

nikibobi commented 11 years ago

Thanks for the explanation. I might start working on something like this. Maybe I'll just make a markdown DDoc template.