Adding modules to modules.ddoc is tedious
Opened this issue · 11 comments
Regularly I forget adding new modules to modules.ddoc. Is there any way to automate this process?
One way you could solve this problem is to walk the file system hierarchy of your source base and generate modules.ddoc from that. Perhaps some utility to do this could be added to the generator script.
@jkm Would you prefer passing all your modules to the generator script on the command line, or just pointing it to a root directory which it walks to find all modules?
I personally prefer the former, because the latter would make it impossible to not include internal modules.
The first option looks better. Ideally I won't need the modules.ddoc file at all. But I see that this is difficult to achieve.
The modules.ddoc file has to exist in some capacity, it's original purpose is to populate the module list in the sidebar. The format of this file is traditional; it was introduced in candyDoc and is also used in cuteDoc. VisualD has a feature where it can automatically generate a file in this format for all modules in the project.
Hence, the generator tool just reuses this existing information so you don't have to repeat it on the command line. It's possible to reverse the process and make the tool automatically generate the modules.ddoc file, but then you can't take advantage of existing files from projects which used to use candyDoc, or files generated by IDEs.
When it comes to generating modules.ddoc from the sources, it's also worth mentioning that this would need to support some kind of blacklist to filter out internal modules and so forth. It's also not apparent which packages should be included in the documentation.
@JakobOvrum I think the idea is that we'll feed modules to the generator script on the command line and it'll just populate modules.ddoc with that; that way, you can trivially leave out internal modules.
Of course we should still support hand-written modules.ddoc files.
btw, I'm completely open to this as long as it fits nicely. Currently, the generate tool uses the first argument as the location of the root of the project, i.e., the path passed as -I to DMD. This potentially conflicts with the suggested syntax.
However, the current design isn't very good anyway because it only allows for one root that way, others have to be passed as -I manually, which looks deceptive when it's actually just another root.
Suggestions with details about how it would actually work would be appreciated.
On a side note I have problems when generating documentation if there are modules with the same name but in different packages. The documentation file is overriden. This a dmd problem. I created a pull request for dmd to fix this.
dlang/dmd#1117
Have you encountered this yourself?
@jkm, yes, you can use the -op command line option to leave the path as-is.
I think the generator tool avoids this problem by calling DMD once for every file and using the -Df option.
I could not use the generator tool because I do not know how to set import paths. Do you know how to do this? For the moment I'm using -op with dmd. Leading to the same directory hierachy as for the module. But this does not work with bootDoc.
@jkm, command line arguments that aren't processed by the generator tool are passed onto the compiler. You can just pass -Isomepath as with the compiler.
I had a look a the code. I was passing -Isomepath before the root project but you have to do it after it. Thanks.