About the Documentation — boto v2.27.0

### Navigation

- index
- modules |
- next |
- previous |
- boto v2.27.0 »

# About the Documentation

boto’s documentation uses the Sphinx documentation system, which in turn is based on docutils. The basic idea is that lightly-formatted plain-text documentation is transformed into HTML, PDF, and any other output format.

To actually build the documentation locally, you’ll currently need to install Sphinx – `easy_install Sphinx` should do the trick.

Then, building the html is easy; just `make html` from the `docs` directory.

To get started contributing, you’ll want to read the ReStructuredText Primer. After that, you’ll want to read about the Sphinx-specific markup that’s used to manage metadata, indexing, and cross-references.

The main thing to keep in mind as you write and edit docs is that the more semantic markup you can add the better. So:

    Import ``boto`` to your script...

Isn’t nearly as helpful as:

    Add :mod:`boto` to your script...

This is because Sphinx will generate a proper link for the latter, which greatly helps readers. There’s basically no limit to the amount of useful markup you can add.

## The fabfile

There is a Fabric file that can be used to build and deploy the documentation to a webserver that you ssh access to.

To build and deploy:

    cd docs/
    fab deploy:remote_path='/var/www/folder/whatever' --hosts=user@host

This will get the latest code from subversion, add the revision number to the docs conf.py file, call `make html` to build the documentation, then it will tarball it up and scp up to the host you specified and untarball it in the folder you specified creating a symbolic link from the untarballed versioned folder to `{remote_path}/boto-docs`.

### Navigation

- index
- modules |
- next |
- previous |
- boto v2.27.0 »