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
- Easy to track with git
- Plus all the benefits of GitHub like pull requests, issue management, and a code review system
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:
Note: You need to install Sphinx to preview your changes.
Once you've made your changes to the documentation, you need to rebuild the HTML
files using make html.
cd freeseer-docs/
make html
Your updated HTML files should be infreeseer-docs/build/html/.
Open the relevant HTML file(s) with your favourite web browser!
Tip: GitHub can render reStructredText. View an .rst file to see how it looks.
Tip: View the underlying reStructuredText of any webpage built with Sphinx by clicking the "Show Source" link on the page you're on.
Once your changes are complete and look fine, they are ready to be deployed to the online documentation at http://freeseer.github.com/docs.
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!
Note: This script is only intended for people with write access to the freeseer.github.com repo. It builds the Sphinx output, copies the newly produced HTML files to your local freeseer.github.com repo, then pushes them to GitHub.