The Freeseer team uses a tool called Sphinx to create the project's documentation.
Sphinx uses reStructuredText as its markup language.
We chose Sphinx for several reasons:
- Easy to create intelligent and beatiful documentation
- Common tool for documenting projects written in Python
- Multiple output formats (HTML, LaTeX, manual pages, and plain text)
- Handles Python code, including highlighting, docstrings, and more
The best place to start is the Sphinx website. But if you're in a hurry, here's the gist of what you need to know:
Install the Sphinx package with sudo easy_install -U Sphinx.
For an overview of basic tasks:
For a brief introduction on reStructuredText concepts and syntax:
Tip: View the underlying reStructuredText of any page built with Sphinx by clicking the "Show Source" link on the page you're interested in.
Once you've made your changes to the documentation, preview them by rebuilding
the output files with make html.
The default build directory is ./build/.
We want the files in ./build/html/ to go to the
freeseer.github.com repo.
A script is provided to easily build and publish the documentation online:
$ ./publish
To add your own one-liner commit message, add it as an argument:
$ ./publish 'Fix a typo.'
Or for a more manual approach, you can place the output directly in your local freeseer.github.com repo:
$ sphinx-build -b html source path/to/freeseer.github.com/docs/
# Don't forget to commit and push the changes in freeseer.github.com!