Maybe not, pydoc-markdown (https://github.com/NiklasRosenstein/pydoc-markdown) looks like it just yanks out the right parts, and doesn't do any filtering or manipulating. Score!
OK, #python question: How do I generate docs for an embedded python project that uses a #SWIG generated library? #pydoc #pdoc and the like rightly complain about non-existent modules, but all the information I want is contained in docstrings and type annotations, so it *should* be possible to generate docs right?
Is there a tool for this?
Discovered, or possibly rediscovered, that for documenting Python modules « python -m pydoc -w png » will produce HTML documentation of the png module. And pydoc is in the Python Standard Library. AFAICT the only styling is automatically produced hyperlinks. I had a quick look at the code (to see if there were any undocumented styling features), and my impression was "plenty of attack surface here". (for example, pydoc includes a web server).
I don't quite understand that difference. #PyDoc uses either docstrings or the comments above a function/module/class/etc. as the comment I'd expect Sphinx to do the same:
https://docs.python.org/3/library/pydoc.html (see paragraph two).
@serge many of the projects we use in Python, like #Flask, are documented using #Sphinx, which can be configured to automatically generate API documentation from Python source code:
https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html
This is (similar to the #yardoc and #rdoc situation) backwards compatible with #pydoc, though much more expressive due to the machine-readable format for defining parameters, return values and potential exceptions:
https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html
#python stdlib has a generated code documenter shoved into it: #pydoc. It has a lot of design problems, top of which is that it works poorly as a pure CI task to generate static HTML.
I forked it and made it at least usable, albeit still ugly.
https://github.com/matthewdeanmartin/pydoc_fork
Next step would be to use modern website templating. Maybe if it ever got attention & I felt peer pressure to improve it again.
