4 ms·
Ask HN: 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?
- pftg 5y agoThe most closest tools is Cucumber
- billconan 5y agohttps://stackoverflow.com/questions/16938760/measuring-documentation-coverage-with-doxygen https://stackoverflow.com/questions/16938760/measuring-docum...
- tstack 5y agoI'm asking about end-user documentation, like a manual. Not, developer documentation. Sorry if that wasn't more clear.
- westurner 5y ago"[Python-Dev] Should set objects maintain insertion order too?" https://mail.python.org/archives/list/python-dev@python.org/message/6OWPRNUXCK776G5H53RAP3OPHBNMK6D7/ 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#metadata https://docutils.sourceforge.io/docs/ref/rst/directives.html... RST field lists: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists https://docutils.sourceforge.io/docs/ref/rst/restructuredtex... `sphinx-apidoc -M`: https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html 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 https://github.com/sphinx-contrib/apidoc awesome-sphinxdoc: https://github.com/yoloseem/awesome-sphinxdoc https://github.com/yoloseem/awesome-sphinxdoc Requirements traceability: https://en.wikipedia.org/wiki/Requirements_traceability https://en.wikipedia.org/wiki/Requirements_traceability Test coverage: https://en.wikipedia.org/wiki/Code_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 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)
- westurner 5y ago- [ ] SCH: SEON OWL ontology could grow a "Documentation"/"Docstring" rdfs:Class/owl:Class and requisite domains on possibly already covering properties to describe the URI-traceable relations between the artifacts: https://github.com/sealuzh/onts-seon https://github.com/sealuzh/onts-seon : > SEON consists of multiple ontologies, for example to describe stakeholders, activities, artifacts, and the relations among all of them. The ultimate goal is to facilitate the implementation of tools that help software engineers to manage software systems over their entire life-cycle. jupyter-book (Sphinx (docutils), myst-parser, jupyter notebooks) > #879 "Generate OpenGraph metadata for social previews and cards" https://github.com/executablebooks/jupyter-book/issues/879#issuecomment-1074280450 https://github.com/executablebooks/jupyter-book/issues/879#i...
- Irongirl1 5y agohttps://www.producthunt.com/posts/create-documentation 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/ https://www.tango.us/ although this one seems aimed at workflow onboarding.