Fork me on GitHub
#cljdoc
<
2023-03-03
>
Noah Bogart16:03:05

I just published a library and the docs show up, looking great. The "Namespaces" side is a little bulky cuz I have a lot of namespaces. Is it possible to exclude a whole directory of namespaces?

āœ… 2
seancorfield16:03:40

Since namespaces are not hierarchical, the "directory" doesn't mean anything. You can exclude a namespace by using the ^:no-doc metadata on its name, so you'd have to do that for all the nses you wanted to exclude.

šŸ‘ 2
Noah Bogart16:03:05

cool, that makes sense

lread21:03:11

@UEENNMX0T fwiw, one thing I noticed as a clj-commons project maintainer is that many lib authors don't bother to distinguish their library's public API. This makes things tricky down the road because folks will rightly assume everything is public and use it. And what should have been internal implementation details cannot be changed without breaking usage. Using :no-doc (a convention invented by codox) is a great way to tell cljdoc that a var or ns is not part of the public API. But an even stronger message to users is to also: ā€¢ ensure private vars are marked as private ā€¢ move all other internals to implementation namespaces, using impl seems to be a common convention, ex: https://github.com/lread/test-doc-blocks/tree/main/src/lread/test_doc_blocks/impl

šŸ‘ 2
Noah Bogart21:03:25

Yeah, I asked about directory because I have 73 namespaces in https://cljdoc.org/d/io.github.noahtheduke/splint/0.1.69/api/noahtheduke.splint.rules.lint and will have even more in the future, and each of these is an implementation detail. I've written a "generate docs" script that extracts the necessary doc info and puts into a https://cljdoc.org/d/io.github.noahtheduke/splint/0.1.69/doc/rule-documentation/lint in the docs/ folder, which I've included in my cljdoc.edn file. I'll just use sed to add ^:no-doc to the namespaces and publish another version when I get some time.

lread21:03:51

Coolio @UEENNMX0T! Looking forward to playing with splint!