www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Generate documentation from ddoc

reply Mike Shah <mshah.475 gmail.com> writes:
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?

---



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`

---



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:

1. Main question: Can I use ddocs to generate documentation on a 
per-source file level (and effectively ignore imports)?
2. 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.
Dec 06 2024
parent reply "Richard (Rikki) Andrew Cattermole" <richard cattermole.co.nz> writes:
Looks like you'll need to use dmd as a library and run the ddoc 
generator manually.

Here is where its being called from:

https://github.com/dlang/dmd/blob/master/compiler/src/dmd/main.d#L682

My only concern is its running after semantic analysis. I don't know how 
good the output will be without it.
Dec 06 2024
parent reply Mike Shah <mshah.475 gmail.com> writes:
On Friday, 6 December 2024 at 20:53:29 UTC, Richard (Rikki) 
Andrew Cattermole wrote:

 Looks like you'll need to use dmd as a library and run the ddoc 
 generator manually.

 Here is where its being called from:

 https://github.com/dlang/dmd/blob/master/compiler/src/dmd/main.d#L682

 My only concern is its running after semantic analysis. I don't 
 know how good the output will be without it.



Thanks Rikki for pointing me to the right place in the internals!

I'll try to dive in a bit more as it warrants.

I really only need to crawl through and display lots of source, 
it would just be nice if I could also provide the ddoc help 
alongside the source to provide context.
Dec 06 2024
parent reply Bradley Chatha <sealabjaster gmail.com> writes:
On Friday, 6 December 2024 at 21:51:28 UTC, Mike Shah wrote:

 ...


It's half baked from a UX perspective, but I have a WIP tool for 
this since I got annoyed at having to have a fully compiling 
setup just to get docs as well: https://github.com/Juptune/marmos

There's a demo repo here with a script you could probably 
repurpose for your own project: 
https://github.com/Juptune/marmos-docfx-demo
Dec 06 2024
parent reply Mike Shah <mshah.475 gmail.com> writes:
On Friday, 6 December 2024 at 23:06:40 UTC, Bradley Chatha wrote:

 On Friday, 6 December 2024 at 21:51:28 UTC, Mike Shah wrote:

 ...


 It's half baked from a UX perspective, but I have a WIP tool 
 for this since I got annoyed at having to have a fully 
 compiling setup just to get docs as well: 
 https://github.com/Juptune/marmos

 There's a demo repo here with a script you could probably 
 repurpose for your own project: 
 https://github.com/Juptune/marmos-docfx-demo


Near, thanks for sharing this! I see you're using DMD as a 
library for this!
Dec 06 2024
next sibling parent Mike Shah <mshah.475 gmail.com> writes:
On Friday, 6 December 2024 at 23:57:01 UTC, Mike Shah wrote:

 On Friday, 6 December 2024 at 23:06:40 UTC, Bradley Chatha 
 wrote:

 On Friday, 6 December 2024 at 21:51:28 UTC, Mike Shah wrote:

 ...


 It's half baked from a UX perspective, but I have a WIP tool 
 for this since I got annoyed at having to have a fully 
 compiling setup just to get docs as well: 
 https://github.com/Juptune/marmos

 There's a demo repo here with a script you could probably 
 repurpose for your own project: 
 https://github.com/Juptune/marmos-docfx-demo


 Near, thanks for sharing this! I see you're using DMD as a 
 library for this!


Neat*
Dec 06 2024
prev sibling parent Bradley Chatha <sealabjaster gmail.com> writes:
On Friday, 6 December 2024 at 23:57:01 UTC, Mike Shah wrote:

 Near, thanks for sharing this! I see you're using DMD as a 
 library for this!


Yeah it was definitely a little obtuse trying to figure out how 
to get everything working, but it works kinda well in the end!

Tons of work left before I'm happy with the tool though, so if 
you do give it a try I apologise for it being confusing/annoying 
to setup; especially since the only documentation generator 
supported right now is a .Net-oriented tool.
Dec 07 2024