PageRenderTime 18ms CodeModel.GetById 15ms app.highlight 1ms RepoModel.GetById 1ms app.codeStats 1ms

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

Relevant Search: With Applications for Solr and Elasticsearch

For more in depth reading about search, ranking and generally everything you could ever want to know about how lucene, elasticsearch or solr work under the hood I highly suggest this book. Easily one of the most interesting technical books I have read in a long time. If you are tasked with solving search relevance problems even if not in Solr or Elasticsearch it should be your first reference. Amazon Affiliate Link
#
ReStructuredText | 59 lines | 38 code | 21 blank | 0 comment | 0 complexity | bbed0c3ec5101c6b5e82c737f4a338be MD5 | raw file
 1.. _documentation:
 2
 3=======================
 4About the Documentation
 5=======================
 6
 7boto's documentation uses the Sphinx__ documentation system, which in turn is
 8based on docutils__. The basic idea is that lightly-formatted plain-text
 9documentation is transformed into HTML, PDF, and any other output format.
10
11__ http://sphinx.pocoo.org/
12__ http://docutils.sf.net/
13
14To actually build the documentation locally, you'll currently need to install
15Sphinx -- ``easy_install Sphinx`` should do the trick.
16
17Then, building the html is easy; just ``make html`` from the ``docs`` directory.
18
19To get started contributing, you'll want to read the `ReStructuredText
20Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__
21that's used to manage metadata, indexing, and cross-references.
22
23__ http://sphinx.pocoo.org/rest.html
24__ http://sphinx.pocoo.org/markup/
25
26The main thing to keep in mind as you write and edit docs is that the more
27semantic markup you can add the better. So::
28
29    Import ``boto`` to your script...
30
31Isn't nearly as helpful as::
32
33    Add :mod:`boto` to your script...
34
35This is because Sphinx will generate a proper link for the latter, which greatly
36helps readers. There's basically no limit to the amount of useful markup you can
37add.
38
39
40The fabfile
41-----------
42
43There is a Fabric__ file that can be used to build and deploy the documentation
44to a webserver that you ssh access to.
45
46__ http://fabfile.org
47
48To build and deploy::
49
50    cd docs/
51    fab deploy:remote_path='/var/www/folder/whatever' --hosts=user@host
52
53This will get the latest code from subversion, add the revision number to the 
54docs conf.py file, call ``make html`` to build the documentation, then it will
55tarball it up and scp up to the host you specified and untarball it in the 
56folder you specified creating a symbolic link from the untarballed versioned
57folder to ``{remote_path}/boto-docs``.
58
59