Publish API documentation

[dplanella]

It struck me that there was no online API documentation, which I'm assuming is simply because no one has worked on it yet.

I've put together a readthedocs branch with Python docstrings for the Encoder module (the only pure Python module in the repo), and I've manually added API documentation for the PWM module. I used sphinx to build the HTML docs locally, with which the changes are really minimal (just 3 new files under the docs directory).

I've then imported this branch to readthedocs for a proof of concept, and here it is:

http://adafruit-bbio.readthedocs.io

The nice things about readthedocs are that the maintenance is minimal (doc rebuilds are triggered from github commits) and that it allows for automatic versioning. I.e. doc builds can be tied to a particular release, so that there can be doc urls for v1.0.8, v.1.0.9, etc., along with 'stable' and 'latest' aliases.

To test this on a local checkout of that branch:

sudo pip install sphinx
cd docs
make html

And then open the docs/_build/html/index.html page with your browser. Note that the local HTML theme is the Sphinx default one, which is different than Readthedoc's online one.

Before I submit the branch, feedback and discussion would be welcome.

[pdp7]

@dplanella Thanks, great idea! I was able to build the html files with those commands using your branch.

Please open a pull request.

For reference:

[pdp7@skylake docs]$ make html
Running Sphinx v1.6.5
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                          
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                           
generating indices... genindex py-modindex
writing additional pages... search
copying static files... WARNING: html_static_path entry u'/home/pdp7/dev/ssh/dplanella/adafruit-beaglebone-io-python/docs/_static' does not exist
done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 1 warning.

Build finished. The HTML pages are in _build/html.

[dplanella]

@pdp7 thanks for the feedback. I've now submitted PR #219 to address this.

[pdp7]

I added the documentation generation config under docs, as it seems to be the adopted convention for Sphinx. There is a doc directory in the source tree that contains some markdown files with testing instructions. Right now the source tree layout is a bit confusing with these two, but I wouldn't want to mix all these files. Could the markdown files be moved to the test directory?

I've moved the 'doc' dir to 'tests/notes'.

[pdp7]

@dplanella I tried the access http://adafruit-bbio.readthedocs.io/en/latest/ and see this message:

Permission Denied

You don't have the proper permissions to view this page. Please contact the owner of this project to request permission.

Do you know how I can make it publicly accessible?

[dplanella]

@pdp7 I disabled that URL in purpose. I used it for the initial testing, and when my docs branch was merged I switched to http://adafruit-beaglebone-io-python.readthedocs.io/en/latest. It's a longer URL to type, but for some reason it also got better Google search ranking results when looking for e.g. "beaglebone python api documentation". I can remove the adafruit-bbio project altogether if that causes confusion.

You should have full admin permissions on http://adafruit-beaglebone-io-python.readthedocs.io. If that does not work for some reason, let me know and we can sort it out. Also, I believe that is the only project you should see when you log into readthedocs.io.

All that has made me notice that the GitHub webhook on readthedocs seems to have stopped working after 1.0.9 for no particular reason. That means:

• The 1.0.10 label does not automatically appear on the active upstream versions page
• Documentation builds of the active branches/tags do not happen automatically upon upstream commits. (Currently only the upstream master branch is enabled, as the '/latest' URL.)

We might need to take this to the readthedocs folks, as as far as I can tell, there is no visibility on the admin interface on what the webhook is doing. One can simply delete, resync or create a webhook. I've tried resyncing, but that gives me a "Fail. Check back in a bit!" :/

Active upstream versions:
https://readthedocs.org/dashboard/adafruit-beaglebone-io-python/versions/

GitHub webhook:
https://readthedocs.org/dashboard/adafruit-beaglebone-io-python/integrations/

That's a bit of a bummer, as one of the main goals was for the API documentation to be nearly maintenance free...

[pdp7]

@dplanella thanks for the detailed explanation.

[dplanella]

@pdp7 no worries. I filed an RT on readthedocs - readthedocs/readthedocs.org#3587

[pdp7]

@tannewt @tdicola @ladyada

Hi, it does not seem that I can access this URL:
https://github.com/adafruit/adafruit-beaglebone-io-python/settings/hooks

Does this work for you?

@dplanella had asked me check that URL

[dplanella]

@pdp7 great, thanks!

Depending on how busy these folks are, another alternative that we have is to do a commit on adafruit-beaglebone-io-python. That should trigger a documentation build now that the readthedocs bug is reportedly fixed. If it does, we're all good. If not, then either the rtd bug is not fixed or it was not the cause for the automatic builds not being triggered.