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:
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!