Making use of Sphinx autodoc for API docs

[gtaylor]

I was trolling through the docs on RTD and noticed that the Client API section is currently being done manually. Since I am a glutton for punishment, I figured I'd see if you would be interested in a pull request that converts this to use Sphinx's autodoc. This would involve moving a lot of what is in that api.md to the source itself.

The benefit of this is that you end up with detailed documentation within the source itself, and it becomes very easy to update docstrings as code is touched.

Just in case an example is needed, we'll continue using boto+dynamodb as an example.

• Layer1.put_item() source code: https://github.com/boto/boto/blob/develop/boto/dynamodb/layer1.py#L347
• The resulting auto-doc'd page: http://boto.cloudhackers.com/en/latest/ref/dynamodb.html#boto.dynamodb.layer1.Layer1.put_item

I'd suggest starting with this, then working on a more conversational How-To page that shows some usage examples. I can't promise anything, but I'd potentially be interested in helping as I learn docker-py (and Docker) better.

If you were interested in the autodoc'd API page, that's probably something I could volunteer a pull request for.

[shin-]

Hi there,

Thanks for chipping in and sharing your thoughts. I admit to being kind of torn on the issue of in-code documentation. It does have some nice upsides as you describe, but my main issue with it is adding bloat to files that should aspire to be as concise as possible (I know client.py fails big time there, and it's something I hope to be able to fix at some point). But in my opinion this makes reading and maintaning the actual code more tedious than it should be.

But I would love to hear other people's opinions on this, as like I said, I can see both sides of the argument here.

[nir0s]

I've been using Sphinx for a long while now and it's great. I think docstrings make everything more easily understandable. You don't have to skip to the md files everytime you wanna understand what's going on within the code. Sphinx does require that you write RST (other than for the auto-generated API pages) unless you're willing to work with pandoc (I do).

Bottom line is, I'd definitely move from mkdocs to sphinx.

[gtaylor]

I don't care as much to argue about which documentation system to use (though I do subjectively prefer Sphinx), but almost any modern editor is able to collapse (or auto-collapse) docstrings. As a consequence, I tend to see the "bloat" counter-argument as a weak one.

As @nir0s says, you do get some maintainability benefits, and you also pick up on nice features like being able to cross-reference other modules/classes/functions in the docs (:py:class:somemodule.Class``). You can still do conversational/tutorial style docs to complement your API reference pages, too.

[rutsky]

1. Currently API documented in Markdown looks visually awful: there is no distinction between argument names, types, they all just plain text, e.g.:

   Params:

   • path (str): Path to the directory containing the Dockerfile
   • tag (str): A tag to add to the final image
   • quiet (bool): Whether to return the status

   They can be manually formatted, but it's painful and not obvious with limited abilities of Markdown, e.g.:

   Params:

   • path (str): Path to the directory containing the Dockerfile
   • tag (str): A tag to add to the final image
   • quiet (bool): Whether to return the status

   Sphinx provides good formatting out of the box --- just see example, provided by @gtaylor.

2. IMO, having documentation close to source code is much better that having it in separate place.
   It's easier see what function does in IDE, it's easier to sync function behaviour changes with documentation.

[bfirsh]

Fixed in #1186!