Generate docs once and upload
iandanforth opened this issue · comments
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
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:
- Requests sphinx config
- Sphinx Getting Started page
- Sphinx Autodoc for dummies tutorial
- 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.