bsabuncu / freeseer-docs Goto Github PK

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:

• Sphinx tutorial

For a brief introduction on reStructuredText concepts and syntax:

• reStructuredText Primer
• Sphinx cheat sheet

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!