nim doc recursive should allow doc generation only for public proc.

[mratsim]

Currently using the nim doc for the global project via

nim doc --project --index:on --git.url:<url> --git.commit:<tag> <main_filename>.nim
nim buildIndex -o:htmldocs/theindex.html htmldocs

will recursively generate doc for each Nim file of the project.

However, projects may have public procs that are internal only and public procs that are actually exposed to the users.

Currently there is no way to only keep those procs.

[timotheecour]

However, projects may have public procs that are internal only

how do you distinguish whether an exported symbol is internal only?

[mratsim]

It's exported/reexported from the main file that end user import.

[timotheecour]

personally I prefer more doc than less doc, as soon enough you need to read docs for internal procs when things go wrong or you need to customize or understand implementation, so if this feature is introduced and ppl start using it may actually hurt more.

You already get almost what you want: eg, for https://github.com/nitely/nim-regex,

nim doc --project --index:on --outdir:htmldocs src/regex.nim
navigate on the main page and you'll get all your non-internal exported symbols, plus the re-exported ones at the bottom which are 1 click away.

So you could inline those re-exported symbols in the main project html file, but then those symbols might depend on other private symbols in their definition, so you'd get incomplete information: eg: Regex is re-exported, but depends on Transitions which itself is not re-exported.

Also, inlining exported symbols would mean that you'd end up inlining a lot of symbols in case some of those re-exports are modules.

That being said, I'd be ok with following:

proposal

• nim doc --project generates docs recursively, like today; users can choose to just look at main page
• each re-exported symbol that's not a module gets its definition inlined (but with some indicator of which module it comes from); some of the symbols in that definition (eg Transitions in above nim-regex example) would not be defined in this module but would have an href to where they're defined
• each link to a re-exported symbol from that page links to the inlined definition
• the re-exported symbol itself has an href linking to its original definition in another module
• each of those rules apply to all modules, not just the main project one; it basically makes re-exports inlined with sane href semantics

and finally, for non-open source projects that want their internal docs not shown (seems like a valid use case), an option nim doc --docmainonly can be provided, which will make sure there are no outgoing broken hrefs and would only generate docs for top-level module

[Menduist]

My two cents, in libp2p we have a lot of exported-but-not-public procedures (probably 70% of our procedures actually)

The big difference between and exported and a public procedure is that we don't necessarily keep backward compatibility for it. (we have to export it for our internal usage)

A solution I found is to add a .public. pragma on every actually-public procedure, and make nim-doc hides the non-public ones by default. In the HTML file, there is a button to show every procedure, if you want to see them

See here: vacp2p/nim-libp2p#650

I like this approach, because in the code you can see which procedures you should not break at a glance (vs hacking to check if they are re-exported somewhere else), and same for someone wanting to use the library, it's easy to know if you're supposed to use something or not.

Though currently it relies on an ugly nim doc hack that I would like to improve

[Nycto]

Is there any consensus here? I did a prototype yesterday of the opposite of what @Menduist proposed. Basically, instead of ‘.public.’ it implements ‘.nodoc.’, but that could easily be flipped around and put behind a flag.

I do agree that a “flattened” doc file that merged all re-exported files would be a better user experience, though.

But also, maybe both mechanisms could work better together?

[Menduist]

@Nycto do you have your prototype available somewhere?

It seems that everyone wants something different, maybe it should be customizable after all

[Nycto]

Yeah, absolutely. Here is my change: Nycto@ef3f3c7

I'm unclear if there are any unit tests for this code, so I haven't bundled it as a pull request yet.