Announcing pydoc.io beta | Hacker News Reader

Announcing pydoc.io beta

blog.readthedocs.com

76 pointsd0vs24 comments

Open articleView on HN

Just FYI `https://pydoc.io/` doesn't load but www.pydoc.io does (at least for me).

Need nginxdoc.io now.

http://showthedocs.com/query?lang=nginx&q=server+%7B%0D%0A++...

Thanks. This should now be fixed.

Seems like a worthwhile initiative (and it appears that Mozilla agrees).

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.

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.

I ended up writing my own script. Now I simply do

    ./docstring2markdown.py modulename [github_master_url] > README.md

And it generates a Markdown API like this one: https://github.com/boppreh/keyboard#api . 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.

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.

I had that same frustration and wrote pdoc: https://github.com/BurntSushi/pdoc

Example output: http://pdoc.burntsushi.net/pdoc

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.

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

I'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

Sphinx 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

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

Sphinx'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.

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

(I've provided this feedback in the past to readthedocs several times, but never even got an acknowledgement.)

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

Isn't conf.py executed? You should be able to put whatever execution step you want in it.

The last step is to run sphinx-build, and that is what uses conf.py.

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

Question: Would anyone here pay for high quality generated python docs with a built in sandbox and "live" example text areas (a place where you can see how the API actually works). I'd like to do this for about 1/2 dozen languages and opensource projects, but don'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?

You mean like we have on runkit.com? https://runkit.com/npm/ramda (or the live examples on lodash.com which are also powered by runkit)

Who cannot use a Python interpreter to see how the API actually works?

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't causing the Python ecosystem to abandon documentation written by humans with this emphasis on Java-style autogeneration.

Could you elaborate on this? Aren't auto-generated docs produced from comments written by humans? What exactly is wrong with that?

So, to take an example, here's the documentation for a library I maintain:

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 think you're throwing the baby out with the bath water, and I think module level comments are a perfectly reasonable place to address most of your concerns. (I don't know why they're "hacky.") Look for example at these docs, which are completely auto-generated from comments in the source: https://docs.rs/regex ... Here's another example: https://docs.rs/fst

Note that I do think there's a limit to what auto-documentation can provide, but I think you're selling it pretty short.

Reply on news.ycombinator.com