Generating symbol list in ddoc (with dub)

I have a rather large single documentation page and I want to generate a symbol list (Jump to: on phobos docs, see std.compiler) with dub --build=ddoc because it is not there by default (current documentation page)

I would not want to include a list of all symbols with links in the code for obvious reasons.

I know that this is possible with ddox or javascript, but is there any way to do this using only vanilla ddoc so maintenance effort can be kept at a minimum? Thanks

Edit: I want to generate a listing for both global symbols, but also for members of classes and put the table near the class.


  • Ddoc is a macro system. It just replaces one thing with something else. The compiler defines certain macros for you (which you can redefine), and for actually generating a documentation page using ddoc, the compiler takes the documentation comments from the module, its list of documented symbols, etc. and basically generates a .dd page like you'd have when creating something like the dlang.org website. It's a bunch of text with ddoc markup. That ddoc markup is then replaced with whatever those ddoc macros are defined to be replaced with. By default, that's a bunch of html geared towards creating a web page, but those macros could be redefined to generate different html than the default or to generate something completely different like latex.

    However, ultimately, all you're getting is the equivalent of a .dd page where you can affect what the results are by redefining the macros and thus redefining how one piece of text is converted into another. You have zero capability to iterate a list of symbols or do anything particularly turing complete. All you get is macro expansion.

    That's why dlang.org uses javascript to generate the jump to links, and that's why the build process for dlang.org actually has a small D program that it runs to generate the ddoc for the navigation bar with the module list. ddoc can't do any of that. And that's why a tool like ddox uses the json output from the compiler to get at the symbol list and documentation info and generate its own thing.

    So, no, you can't do anything like what you're trying to do with just standard ddoc. Really, the only options are to use javascript so that the browser can manipulate the result when viewing the document, to manipulate and/or generate ddoc with an external program, or to generate the documentation with a completely different tool such as ddox.

    ddoc is a great macro system and fairly powerful as such, but if you're trying to do anything fancier than affect how the generated documentation looks, ddoc really doesn't get you there - at least not without the help of other tools to generate or manipulate either the ddoc that's processed or the results of processing the ddoc.

    Ddoc documentation: https://dlang.org/spec/ddoc.html

    There are some alternative documentation generators (which may or may not use ddoc) listed here: https://wiki.dlang.org/Open_Source_Projects#Documentation_Generators