gendocs

This is a program for simplifying ddoc generation.

It ensures that the names of the generated .html files include the full module path (with underscores instead of dots) rather than simply being named after the modules (since just using the module names results in connflicts if any packages have modules with the same name).

It also provides an easy way to exclude files from ddoc generation. Any modules or packages with the name internal are excluded as well as any files that are passed on the command line. And package.d files have their corresponding .html files renamed to match the package name.

Also, the program generates a .ddoc file intended for use in a navigation bar on the side of the documentation (similar to what dlang.org has) uses it in the ddoc generation (it's deleted afterwards). The navigation bar contains the full module hierarchy to allow for easy navigation among the modules in the project. Of course, the other .ddoc files have to actually use the MODULE_MENU macro in the generated .ddoc file, or the documentation won't end up with a navigation bar.

The program assumes a layout similar to dub in that the source files are expected to be in a directory called "source", and the generated documentation goes in the "docs" directory (which is deleted before documentation generation to ensure a clean build).

It's expected that any .ddoc files being used will be in the "ddoc" directory, which isn't a dub thing, but they have to go somewhere.

In addition, the program expects there to be a "source_docs" directory. Any .dd files that are there will have corresponding .html files generated for them (e.g. for generating index.html), and any other files or directories (e.g. a "css" or "js" folder) will be copied over to the "docs" folder.

Note that this program does assume that all module names match their file names and that all package names match their folder names.

Meta

Authors

Jonathan M Davis