/boto-2.5.2/docs/source/documentation.rst
ReStructuredText | 59 lines | 38 code | 21 blank | 0 comment | 0 complexity | bbed0c3ec5101c6b5e82c737f4a338be MD5 | raw file
- .. _documentation:
- =======================
- 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.
- __ http://sphinx.pocoo.org/
- __ http://docutils.sf.net/
- 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.
- __ http://sphinx.pocoo.org/rest.html
- __ http://sphinx.pocoo.org/markup/
- 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.
- __ http://fabfile.org
- 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``.