PageRenderTime 41ms CodeModel.GetById 17ms RepoModel.GetById 0ms app.codeStats 0ms

/boto-2.5.2/docs/source/documentation.rst

#
ReStructuredText | 59 lines | 38 code | 21 blank | 0 comment | 0 complexity | bbed0c3ec5101c6b5e82c737f4a338be MD5 | raw file
  1. .. _documentation:
  2. =======================
  3. About the Documentation
  4. =======================
  5. boto's documentation uses the Sphinx__ documentation system, which in turn is
  6. based on docutils__. The basic idea is that lightly-formatted plain-text
  7. documentation is transformed into HTML, PDF, and any other output format.
  8. __ http://sphinx.pocoo.org/
  9. __ http://docutils.sf.net/
  10. To actually build the documentation locally, you'll currently need to install
  11. Sphinx -- ``easy_install Sphinx`` should do the trick.
  12. Then, building the html is easy; just ``make html`` from the ``docs`` directory.
  13. To get started contributing, you'll want to read the `ReStructuredText
  14. Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__
  15. that's used to manage metadata, indexing, and cross-references.
  16. __ http://sphinx.pocoo.org/rest.html
  17. __ http://sphinx.pocoo.org/markup/
  18. The main thing to keep in mind as you write and edit docs is that the more
  19. semantic markup you can add the better. So::
  20. Import ``boto`` to your script...
  21. Isn't nearly as helpful as::
  22. Add :mod:`boto` to your script...
  23. This is because Sphinx will generate a proper link for the latter, which greatly
  24. helps readers. There's basically no limit to the amount of useful markup you can
  25. add.
  26. The fabfile
  27. -----------
  28. There is a Fabric__ file that can be used to build and deploy the documentation
  29. to a webserver that you ssh access to.
  30. __ http://fabfile.org
  31. To build and deploy::
  32. cd docs/
  33. fab deploy:remote_path='/var/www/folder/whatever' --hosts=user@host
  34. This will get the latest code from subversion, add the revision number to the
  35. docs conf.py file, call ``make html`` to build the documentation, then it will
  36. tarball it up and scp up to the host you specified and untarball it in the
  37. folder you specified creating a symbolic link from the untarballed versioned
  38. folder to ``{remote_path}/boto-docs``.