Generate docs once and upload

[iandanforth]

Document Religiously

• Document every class, interface, method, constructor, parameter, and exception
  • Class: what an instance represents
  • Method: contract between method and its client
  • Preconditions, postconditions, side-effects
    • Parameter: indicate units, form, ownership
• Document state space very carefully

[iandanforth]

Docs will be available from https://iandanforth.github.io/pymuscle-docs/

I investigated the most common way to do this using the Requests library and Scikit-learn and examples. Both of them use Sphinx to autogenerate documentation.

I found the following links useful in getting set up:

1. Requests sphinx config
2. Sphinx Getting Started page
3. Sphinx Autodoc for dummies tutorial
4. Tutorial for connecting sphinx builds with github.io pages

The current setup is as follows

github.com/iandanforth/pymuscle

• docs/

This folder contains the source (rst files) of the docs as well as the build config and tools (makefile).

github.com/iandanforth/pymuscle-docs/

The top level folder of this repo is the target for the build process of the docs.

Locally I have a folder structure like this

pymuscle/ pymuscle-docs/

• help/ <---- This is where the docs repo is cloned.

By running make html from the docs/ dir in the main pymuscle repo and using a build TARGET of ../../pymuscle-docs/ I get output placed into the local pymuscle-docs/html/ dir as desired.

This is then pushed to the pymuscle-docs repo.

That repo is set up to serve the github.io page directly from the master branch.