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.
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.
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.
pip install sphinx
sphinx autogen_html_docs --output /path/to/folder --input /path/to/mymodule_folderMy project has a C module as part of the project, and the documentation (in rst format) is generated. However to generate it requires a "compilation" step, which rtd does not support. "make docs" will correctly do everything necessary.
Sadly rtd tools want to be in charge of all steps, and provide no way of doing the initial build and file generation.
Before that, the following is done:
- Compile the code/module
- Run the example code capturing various pieces of output, putting the final result into a generated .rst file
- Generating more .rst files from various C file sources
- Some additional doc updates (eg inserting some version related info, updating help sections with current --help information for cli tools). These are up to date in git, so rtd wouldn't need to run them, but I do for each release
http://webcolors.readthedocs.io/
Once upon a time, the entire library's documentation was generated from docstrings in the code, but the library very quickly outgrew that as I needed to do things like:
* How to install the library and how to run the tests
* Properly explain the web color model and the history of how it's been implemented in the specifications
* Properly explain how the various ways to specify colors get represented as Python types
* Explain how Python 2/3 compatibility is handled
etc., etc.
There are a ton of things that don't naturally attach to just one function or class, but need to be in the documentation. The hacky compromise solution is a module-level docstring, but now people who want to read source have to scroll through a huge amount of stuff before they see a single line of actual code.
So I'm going to stay far away from auto-generated documentation and "just put it in comments/docstring/etc." for the foreseeable future.
I ended up writing my own script. Now I simply do
./docstring2markdown.py modulename [github_master_url] > README.md
It's not perfect, but I'm quite happy for a ~100loc script.
Hopefully they launch something as easy and I can retire my script.
Example output: http://pdoc.burntsushi.net/pdoc
A suggestion: perhaps it would be worth focusing on the Python standard library, at least initially? I find the 'narrative style' and the code examples in the current documentation is often unhelpful and confusing. And it's such a shame; there's so much good functionality in the standard library. This is just from the perspective of a relative novice, but examples like this (https://docs.python.org/3/library/concurrent.futures.html#co...) are extremely hard to follow because too many concepts (some of which are irrelevant) are all introduced at the same time. I often find myself skipping the official documentation all together and going straight to somewhere like PMOTW or stackoverflow.
Also, focusing on the standard library could be a good way to provide a 'best practice' example that the community could follow.