#pydoc — Public Fediverse posts

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!

#python #markdown #pydoc-markdown

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!

#python #markdown #pydoc-markdown

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).

#Python #pydoc

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).

#Python #pydoc

@serge @helge

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 @helge

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

https://docs.python.org/3/library/pydoc.html

@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

https://docs.python.org/3/library/pydoc.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.

#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.