Is there any way to exclude some units of code from the generated docs? I’ve got some modules and objects that need to be public so the rest of my module can access them, but aren’t considered a public API. Package private, basically.
I’m fine with leaving them as public, but I would like to prevent them from showing up in the docs. Either at a file level, or even an individual proc/type level
Yep, like this:
when not defined(nimdoc):
# put your code here
Hmm. That doesn't seem to solve this problem. The documentation generator is running a full compile pass. So if I put code that is actually being used behind a when not defined(nimdoc) clause, the doc generator fails to compile. For example, trying to generate documentation for this:
when not defined(nimdoc):
proc internalOnly*() =
## A method that is "package private", but needs to be flagged as
## public so the rest of the module can access it. However, it
## should not show up in the documentation
echo "Hello"
proc publicApi*() =
## Public function that users can call
internalOnly()
publicApi()
Yields the following error:
> nim doc example.nim
./example.nim(11, 5) Error: undeclared identifier: 'internalOnly'
candidates (edit distance, scope distance); see '--spellSuggest':
(3, 4): 'internalNew' [proc declared in ~/.choosenim/toolchains/nim-1.6.2/lib/system.nim(263, 6)]
./example.nim(11, 17) Error: attempting to call routine: 'internalOnly'
found 'internalOnly' [unknown declared in ./example.nim(11, 5)]
./example.nim(11, 17) Error: attempting to call routine: 'internalOnly'
found 'internalOnly' [unknown declared in ./example.nim(11, 5)]
./example.nim(11, 17) Error: expression 'internalOnly' cannot be called
You could do something like
when not defined(nimdoc):
proc internalOnly*() =
## A method that is "package private", but needs to be flagged as
## public so the rest of the module can access it. However, it
## should not show up in the documentation
echo "Hello"
else:
proc internalOnly() = discard
proc publicApi*() =
## Public function that users can call
internalOnly()
publicApi()
That should make it compile as long as you don't use runnableExamples.
For anyone else searching, there is a feature request here: