
Announcing pydoc.io beta - d0vs
https://blog.readthedocs.com/announcing-pydoc-io/
======
davecap1
Just FYI `[https://pydoc.io/`](https://pydoc.io/`) doesn't load but
www.pydoc.io does (at least for me).

~~~
overcast
Need nginxdoc.io now.

~~~
karakal
[http://showthedocs.com/query?lang=nginx&q=server+%7B%0D%0A++...](http://showthedocs.com/query?lang=nginx&q=server+%7B%0D%0A++listen+80%3B%0D%0A++server_name+showthedocs.com%3B%0D%0A%7D)

------
spangry
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...](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ProcessPoolExecutor))
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.

------
BoppreH
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](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.

~~~
burntsushi
I had that same frustration and wrote pdoc:
[https://github.com/BurntSushi/pdoc](https://github.com/BurntSushi/pdoc)

Example output:
[http://pdoc.burntsushi.net/pdoc](http://pdoc.burntsushi.net/pdoc)

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

~~~
JelteF
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](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...](https://github.com/JelteF/easyfuse/blob/master/docs/create_doc_files.sh)

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

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

~~~
rogerbinns
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

------
MobiKid
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?

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

------
lorenzosnap
pity that the link is broken

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

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

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

[http://webcolors.readthedocs.io/](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.

~~~
burntsushi
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](https://docs.rs/regex) ... Here's another example:
[https://docs.rs/fst](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.

