Announcing pydoc.io beta

Just FYI `<a href="https:&#x2F;&#x2F;pydoc.io&#x2F;`" rel="nofollow">https:&#x2F;&#x2F;pydoc.io&#x2F;`</a> doesn&#x27;t load but www.pydoc.io does (at least for me).

Seems like a worthwhile initiative (and it appears that Mozilla agrees).<p>A suggestion: perhaps it would be worth focusing on the Python standard library, at least initially? I find the &#x27;narrative style&#x27; and the code examples in the current documentation is often unhelpful and confusing. And it&#x27;s such a shame; there&#x27;s so much good functionality in the standard library. This is just from the perspective of a relative novice, but examples like this (<a href="https:&#x2F;&#x2F;docs.python.org&#x2F;3&#x2F;library&#x2F;concurrent.futures.html#concurrent.futures.ProcessPoolExecutor" rel="nofollow">https:&#x2F;&#x2F;docs.python.org&#x2F;3&#x2F;library&#x2F;concurrent.futures.html#co...</a>) 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.<p>Also, focusing on the standard library could be a good way to provide a &#x27;best practice&#x27; example that the community could follow.

A while ago I tried to use sphinx-autoapi, but the experience was simply frustrating. Too many steps, too many dependencies, the tooling required numerous tweaks to generated good output, and errors were difficult to debug.<p>I ended up writing my own script. Now I simply do<p><pre><code> .&#x2F;docstring2markdown.py modulename [github_master_url] &gt; README.md </code></pre> And it generates a Markdown API like this one: <a href="https:&#x2F;&#x2F;github.com&#x2F;boppreh&#x2F;keyboard#api" rel="nofollow">https:&#x2F;&#x2F;github.com&#x2F;boppreh&#x2F;keyboard#api</a> . Note it includes constants and their values, full method signatures with default values, points out aliases (methods with the same name), keeps everything in the order it was declared, and provides a link to the line number on the source.<p>It&#x27;s not perfect, but I&#x27;m quite happy for a ~100loc script.<p>Hopefully they launch something as easy and I can retire my script.

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.<p>Two major features of Python&#x27;s doc tools that I view as lacking:<p>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&#x27;t seem to provide.<p>I&#x27;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.<p>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.

(I&#x27;ve provided this feedback in the past to readthedocs several times, but never even got an acknowledgement.)<p>My project has a C module as part of the project, and the documentation (in rst format) is generated. However to generate it requires a &quot;compilation&quot; step, which rtd does not support. &quot;make docs&quot; will correctly do everything necessary.<p>Sadly rtd tools want to be in charge of all steps, and provide no way of doing the initial build and file generation.

Question: Would anyone here pay for high quality generated python docs with a built in sandbox and &quot;live&quot; example text areas (a place where you can see how the API actually works). I&#x27;d like to do this for about 1&#x2F;2 dozen languages and opensource projects, but don&#x27;t know if people would pay for it. If you would pay do you think a $5.00 monthly subscription (that you could start and stop as needed), would be too little, too much or just right?

pity that the link is broken

Documentation should be written by people, for people. Autogenerated API docs are as old and common as hills, but are so inferior that their value over readable Python code is negligible to nonexistent. I hope readthedocs isn&#x27;t causing the Python ecosystem to abandon documentation written by humans with this emphasis on Java-style autogeneration.