Note
You are viewing the documentation for an older version of boto (boto2).
Boto3, the next version of Boto, is now stable and recommended for general use. It can be used side-by-side with Boto in the same project, so it is easy to start using Boto3 in your existing projects as well as new projects. Going forward, API updates and all new feature work will be focused on Boto3.
For more information, see the documentation for boto3.
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
.