I'm working on a library that is fairly long. After a single nim file reached about 2000 lines, I realized a refactoring is way over due.
So I broke the file into four source files. And, in past projects, I could often abstract the subtending files so that there was no dependency on the main file. But this one was not so easy because, at a fundamental level, these source files all depended on a comment set of types.
No problem, I simply but the shared types into a common.nim file and had all of them, including the main file import from common. The main file also does export <blah> on each of the types so that the user of the library can also see them. All is good.
Then I used nim doc. Now the very important, and needs to be well documented, types are no longer part of the generated documentation. Nor can I see a way to import them into the documentation.
(for procedures, I simply create stubs. Aka proc abc*(): string = submoduleA.abc(). Not the most performant thing to do, but I get my docs generated.)
I have tried a Linux bash workaround that kind-of-sort-of works with a lot of tweaking and some oddly conditional compilation weirdness:
excerpt from nimble file (pretending the library is called "main"):
task docgen, "Generate HTML documentation":
exec "cat common.nim main.nim > temp.nim && nim doc -o:doc/main.html temp.nim && rm temp.nim"
But I'm really not a fan of that as an answer.
Is there a better way to do this?
Are there any when conditions I could use just for documentation. Aka:
when defined(docgen):
type
ABC = object
## this the fancy ABC object. Use it to track blah and stuff.
blah: int
else:
import common # this imports the REAL type ABC for shared use
import seesaw # brings in "seeSawAction"; that module also imports common
var x = ABC(blah: 4)
let bing = x.seesawAction()
Or, I could just give up and generate two html files and use the "exports" section at the bottom.
Not the end of the world. Just curious if there is a work-around.
I have been looking for such a solution as well.
For now in Arraymancer I call nim doc on each individual files. It works because I've separated public/private API and a file containing public API does not export any "private" proc.
See doc generator: https://github.com/mratsim/Arraymancer/blob/0d57199c/docs/docs.nim and thanks @Vindaar for the contribution. In the past I hacked together a very flaky .nimble (probably my worse piece of code by a long mile (copy-pasta soup after fighting with documentation for hours): https://github.com/mratsim/Arraymancer/blob/a0bdf4ec/arraymancer.nimble#L232-L316
Right now with Weave I'm exploring using mdBook, the Rust doc generator, to generate the prose https://github.com/mratsim/weave/tree/2e528bd2/docs
However I'm lacking tooling/documentation to automatically export all public proc into a JSON API. AFAIK the docgen gained a lot of options since I struggled with it in Arraymancer, --projects flags and such but some are ironically not reflected in the documentation.