3 ms·
This seems like a worth-while effort given the poor state of API documentation tools in Python. I view doc tools as the last major deficiency of the Python ecos
by jitl 10y ago
This seems like a worth-while effort given the poor state of API documentation tools in Python. I view doc tools as the last major deficiency of the Python ecosystem compared to other mainstream programming languages.
Two major features of Python's doc tools that I view as lacking:
No Python doc tool produces well-linked API docs out of the box. What I mean by well-linked docs is that with these systems, all type words in function signatures are hyperlinks, so you can quickly move from a function taking a parameter of type Foo to the documentation for the Foo type. This is a feature that pydoc.io still doesn't seem to provide.
I'd also like to see a local, easily installed tool that can generate documentation like this from just the source code of a project in one command. My previous efforts with Python doc tools had me downloading templates, writing a build pipeline that chained multiple tools together, etc.
All the other major langs that I use have excellent API doc tools than require very little setup or babysitting, and produce well-linked documentation. Java has Javadoc, Golang and Rust both bundle good doc tools, Ruby has Yardoc.
- dozzie 10y ago> No Python doc tool produces well-linked API docs out of the box. What's wrong with Sphinx-generated documentation? > I'd also like to see a local, easily installed tool that can generate documentation like this from just the source code of a project in one command. My previous efforts with Python doc tools had me downloading templates, writing a build pipeline that chained multiple tools together, etc. Ever tried Sphinx? I never needed to download any templates or write a pipeline to generate HTML (for man pages, Sphinx has some formatting off, so I needed to adjust it). Granted, it's a little different from JavaDoc-style tools, as you need to a) mark all the functions and classes to see them documented, and b) provide a skeleton for the pages layout, but this actually gives better control over the resulting documentation and allows to include description of non-API things, like architecture, examples, protocol specifications, or glossary.
- diafygi 10y agoI've tried probably half a dozen times to learn how to generate simple sphinx docs for my side projects. I start reading tutorials, then half a weekend goes by, and I give up because I'm knee deep in templates and rst. Either I'm reading the wrong tutorials or the learning curve for sphinx is much higher than you assume. Where are the tutorials that make it as simple as you say? All I want is something like: pip install sphinx sphinx autogen_html_docs --output /path/to/folder --input /path/to/mymodule_folder
- JelteF 10y agoSphinx really isn't that hard. The default config file is just quite crappy. Check out this one for one of my projects: https://github.com/JelteF/easyfuse/blob/master/docs/conf.py https://github.com/JelteF/easyfuse/blob/master/docs/conf.py Especially this line is quite important so you can put python references between backticks and they will automatically be interlinked: default_role = 'py:obj' This file is also quite useful: https://github.com/JelteF/easyfuse/blob/master/docs/create_doc_files.sh https://github.com/JelteF/easyfuse/blob/master/docs/create_d...
- pekk 10y agoSphinx's own documentation makes it vastly easier than `sphinx autogen_html_docs --output /path/to/folder --input /path/to/mymodule_folder` which reads like a really complicated command line of uncertain meaning.
- ubernostrum 10y agoThere does seem to be a strong cultural bias in Python away from "tools will auto-generate our docs" and toward "auto-generated docs tend to suck, let's produce good hand-written docs". Which is not something more tooling will solve; if people don't write high-quality in-depth docstrings for the tools to pick up, the tools are still not going to give you what you want.