Permalink
Reply
Hello,
tl;dr -- Do I need to write my own parser for documentation, or can ddoc be run on individual files without having to resolve all imports?
A few notes on documentation generation with dmd and gdc
Given this hello world program:
import std.stdio;
void main(){
writeln("hello");
}
For a single file program like above with only imports to phobos ddoc handles this with no problem!
The following will build and put in a folder called 'documentation' a new .html file automatically.
dmd -Dddocumentation/ -c hello.d
Now I had to compile this, so a hello.o object file is generated, but I can clean that up manually. It's simple enough to redirect the output of .o files to a new directory.
Better yet, I found I could use gdc (or probably ldc as well) to do something like:
gdc-12 -fsyntax-only hello.d
The above will just check the syntax of the file which is great, and no generated .o files to worry about (much faster to generate the documentation!)
So now here's my pipeline now that I've switched to gdc for generating documentation:
gdc-12 -fdoc -fdoc-dir=documentation -fsyntax-only hello.d
Main question
Now here's the challenge where I am looking for a solution.
Given this program that has an import(hello_with_imports.d), and let's also say that import is also part of the 'dub' build process:
import mikes_lib;
import std.stdio;
void main(){
writeln("hello");
}
Now when I try to build my 'hello_with_imports.d'
gdc-12 -fdoc -fdoc-dir=documentation -fsyntax-only hello.d
I now get the issue of:
hello.d:1:8: note: Expected 'mikes_lib.d' or 'mikes_lib/package.d' in one of the following import paths:
But I actually don't care so much if this code compiles -- I simply want to parse a single .d file, and get the generated .html file that has identified public functions/classes/unit tests/etc.
So here's a summary of the questions:
- Main question: Can I use ddocs to generate documentation on a per-source file level (and effectively ignore imports)?
- secondary question: Does DMD have an equivalent -fsyntax-only option? Or should I use gdc/ldc?
The other purpose of this investigation is that when I otherwise use ddocs to generate from dub, I get a huge set of .html pages from all of the other dependencies. I'm wanting to avoid having to manually filter those out, and otherwise compile lots of my own .d files (some individual, some as part of dub projects) in one central place.
Note: I understand why it probably makes logical sense for ddocs to only run on a valid compiling program (especially if sources are part of the same module), but regardless it's worth a shot.
