HACKER Q&A
📣 tstack

Tools to generate coverage of user documentation for code


Does anyone know of tools/techniques for generating a coverage report of user documentation over source code? In other words, I'd like to be able to automatically determine when there is documentation missing for an implemented feature or if there is documentation for a feature that was removed.

I'm asking because I've been working on a tool for many years and it's grown large enough that I have a hard time keeping track of what all the parts do and what has and has not been documented. What I'm thinking I'd like to do is add a tag to a piece of source code (C++) and put the corresponding tag in the user docs (RST). Then, during the build, I'd like a report of untagged code, code/docs with matching tags, and code/docs with unmatched tags.

I also feel like there should be at least two levels of documentation to be tracked: 1) the overall feature and 2) fine-details about how the feature behaves under different circumstances. For example, a feature that interacted with the network would have an overall description and some extra notes about how timeouts/retries are handled.

Does anyone have any experience with such a thing or have a similar interest?

  👤 Irongirl1 Accepted Answer ✓
https://www.producthunt.com/posts/create-documentation

This one looks nice, but if it's not quite what you need run the search

"documentation" as I did and a bunch more pop up.

Hth,

bkwlf

Like this: https://www.tango.us/ although this one seems aimed at workflow onboarding.

👤 billconan
https://stackoverflow.com/questions/16938760/measuring-docum...
👤 pftg
The most closest tools is Cucumber
👤 westurner
"[Python-Dev] Should set objects maintain insertion order too?" https://mail.python.org/archives/list/python-dev@python.org/... :

> Are there URIs for Big-O notation that could be added as e.g. structured attributes in docstrings or annotations?

Looks like docutils supports bibliographic fields and a `metadata` directive: https://docutils.sourceforge.io/docs/ref/rst/directives.html...

RST field lists: https://docutils.sourceforge.io/docs/ref/rst/restructuredtex...

`sphinx-apidoc -M`: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

sphinx-contrib/apidoc re-runs sphinx-apidoc on every build to generate the doc stubs: https://github.com/sphinx-contrib/apidoc

awesome-sphinxdoc: https://github.com/yoloseem/awesome-sphinxdoc

Requirements traceability: https://en.wikipedia.org/wiki/Requirements_traceability

Test coverage: https://en.wikipedia.org/wiki/Code_coverage

...

Someday I'd like to be able to express RDF triples in RST; wherein the preceding heading and/or a specific attribute specify the subject URI and then attr/value pairs are predicate/objects. IDK if that's even necessary for this application where you'd have the dotted-path of the __doc__ string to imply the subject URI?

: https://twitter.com/westurner/status/1384081580218408962 :

  How to express #LinkedData in
  - [ ] LaTeX
  - [x] HTML: RDFa, JSON-LD, Microdata
  - [ ] YAML: YAML-LD
  - [ ] Markdown: MyST-Markdown for executablebooks/jupyter-book (Sphinx roles and directives)
  
  - [ ] reStructuredText (docutils)