Tool for documentation coverage

[blythed]

Might be nice to add something to interrogate how many functions/ methods are documented in the code-base.

[tmylk]

If you mean docstrings, then it is possible to add to the linter "D103 Missing docstring in public function". There are currently 204 hits for it on main. And also suggest adding doctest.

However my preferred way is not to build the Documentation with sphinx from docstrings but have several markdown files and use 'mkdocs' package the way FastApi does it. The explanations and formatting doesn't clog the docstrings, plus docs can be updated without touching the code. I don't know a way to automate coverage here though, so it is a bit more work.

[blythed]

If you mean docstrings, then it is possible to add to the linter "D103 Missing docstring in public function". There are currently 204 hits for it on main. And also suggest adding doctest.

However my preferred way is not to build the Documentation with sphinx from docstrings but have several markdown files and use 'mkdocs' package the way FastApi does it. The explanations and formatting doesn't clog the docstrings, plus docs can be updated without touching the code. I don't know a way to automate coverage here though, so it is a bit more work.

Interesting. Do you have links or a high level view of that? How do the doc-strings appear in the interactive python help
my_function?? I couldn't quite follow along from the FastAPI link.

[tmylk]

Here is an example of a docstring appearing on mouse hover in vs code. It is short, much shorter than a Docs website page would be on this function. And I suggest that docstrings stay concise and just cover what the PEP suggests. I see it as a "reference" in Diataxis definition. How do you see it?

I gave FastAPI as an example of docs decoupled from docstrings. This FastAPI docs page goes into a lot more detail than any docstring. The website and individual pages are structured in the order which is best for learning, not for storing code methods in a file like in sphinx docs.