Overhaul docs

This adds contributor docs and cleans up some of the elasticutils usage docs, too. It adds a lot of examples and expands on the existing text. This also adds a requirements-dev.txt which makes it a little easier to install for hacking. Still a lot of docs-work to do, but I think this is a nice first pass.
mozilla · Jun 8, 2012 · 5d96df7 · 5d96df7
1 parent 370f2c8
commit 5d96df7
Show file tree

Hide file tree

Showing 13 changed files with 490 additions and 194 deletions.
diff --git a/docs/configuration.rst b/docs/configuration.rst
@@ -0,0 +1,61 @@
+=============
+Configuration
+=============
+
+ElasticUtils depends on the following settings:
+
+.. module:: django.conf.settings
+
+.. data:: ES_DISABLED
+
+    Disables talking to ElasticSearch from your app.  Any method
+    wrapped with `es_required` will return and log a warning.  This is
+    useful while developing, so you don't have to have ElasticSearch
+    running.
+
+.. data:: ES_DUMP_CURL
+
+    If set to a path all the requests that `ElasticUtils` makes will
+    be dumped into the designated file.
+
+    .. note:: Python does not write this file until the process is
+              finished.
+
+
+.. data:: ES_HOSTS
+
+    This is a list of hosts.  In development this will look like::
+
+        ES_HOSTS = ['127.0.0.1:9200']
+
+.. data:: ES_INDEXES
+
+    This is a mapping of doctypes to indexes. A `default` mapping is
+    required for types that don't have a specific index.
+
+    When ElasticUtils queries the index for a model, it derives the
+    doctype from `Model._meta.db_table`.  When you build your indexes
+    and doctypes, make sure to name them after your model db_table.
+
+    Example 1::
+
+        ES_INDEXES = {'default': 'main_index'}
+
+    This only has a default, so ElasticUtils queries will look in
+    `main_index` for all doctypes.
+
+    Example 2::
+
+        ES_INDEXES = {'default': 'main_index',
+                      'splugs': 'splugs_index'}
+
+    Assuming you have a `Splug` model which has a
+    `Splug._meta.db_table` value of `splugs`, then ElasticUtils will
+    run queries for `Splug` in the `splugs_index`.  ElasticUtils will
+    run queries for other models in `main_index` because that's the
+    default.
+
+.. data:: ES_TIMEOUT
+
+    Defines the timeout for the `ES` connection.  This defaults to 1
+    second.
diff --git a/docs/dev_conventions.rst b/docs/dev_conventions.rst
@@ -0,0 +1,12 @@
+===========
+Conventions
+===========
+
+We follow the code conventions listed in the `coding conventions page
+of the webdev bootcamp guide
+<http://mozweb.readthedocs.org/en/latest/coding.html>`_. This covers
+all the Python code.
+
+We use git and follow the conventions listed in the `git and github
+conventions page of the webdev bootcamp guide
+<http://mozweb.readthedocs.org/en/latest/git.html#working-on-projects>`_.
diff --git a/docs/dev_documentation.rst b/docs/dev_documentation.rst
@@ -0,0 +1,26 @@
+=============
+Documentation
+=============
+
+Conventions
+===========
+
+See the `docmentation page in the webdev bootcamp guide
+<http://mozweb.readthedocs.org/en/latest/documentation.html>`_ for
+documentation conventions.
+
+The documentation is available in HTML and PDF forms at
+`<http://elasticutils.readthedocs.org/>`_. This tracks documentation
+in the master branch of the git repository. Because of this, it is
+always up to date.
+
+
+Building the docs
+=================
+
+The documentation in `docs/` is built with `Sphinx
+<http://sphinx.pocoo.org/>`_. To build HTML version of the
+documentation, do::
+
+    $ cd docs/
+    $ make html
diff --git a/docs/dev_testing.rst b/docs/dev_testing.rst
@@ -0,0 +1,29 @@
+=========================
+Running and writing tests
+=========================
+
+Running the tests
+=================
+
+To run the tests, do::
+
+    DJANGO_SETTINGS_MODULE=es_settings nosetests -w tests
+
+
+.. Note::
+
+   If you need to adjust the settings, copy ``es_settings.py`` to a
+   new file (like ``es_settings_local.py``), edit the file, and pass
+   that in as the value for ``DJANGO_SETTINGS_MODULE``.
+
+   This is helpful if you need to change the value of ``ES_HOSTS`` to
+   match the ip address or port that elasticsearch is listening on.
+
+
+Writing tests
+=============
+
+Tests are located in `tests/`.
+
+We use `nose <https://github.com/nose-devs/nose>`_ for test utilities
+and running tests.
diff --git a/docs/django.rst b/docs/django.rst
@@ -2,13 +2,14 @@
 Django Model Integration
 ========================
 
-Django Models and ElasticSearch indices make a natural fit.
+Django Models and ElasticSearch indices make a natural fit.  It would
-It would be terribly useful if a Django Model knew how to add and remove itself
+be terribly useful if a Django Model knew how to add and remove itself
-from ElasticSearch.
+from ElasticSearch.  This is where the
-This is where the :class:`elasticutils.models.SearchMixin` comes in.
+:class:`elasticutils.models.SearchMixin` comes in.
 
-You can then utilize things such as :func:`~elasticutils.tasks.index_objects` to
+You can then utilize things such as
-automatically index all new items.
+:func:`~elasticutils.tasks.index_objects` to automatically index all
+new items.
 
 .. autoclass:: elasticutils.models.SearchMixin
    :members:

diff --git a/docs/hacking_howto.rst b/docs/hacking_howto.rst
@@ -0,0 +1,35 @@
+.. _hacking-howto-chapter:
+
+=============
+Hacking HOWTO
+=============
+
+This covers setting up a development environment for developing on
+ElasticUtils. If you're interested in using ElasticUtils, then you
+should check out :ref:`users-guide`.
+
+
+External requirements
+=====================
+
+You should have `elasticsearch <http://elasticsearch.org/>`_ installed
+and running.
+
+
+Get dependencies
+================
+
+Run::
+
+    $ virtualenv ./venv/
+    $ . ./venv/bin/activate
+    $ pip install -r requirements-dev.txt
+
+
+This sets up all the required dependencies for development of
+ElasticUtils.
+
+.. Note::
+
+   You don't have to put your virtual environment in ``./venv/``. Feel
+   free to put it anywhere.
diff --git a/docs/index.rst b/docs/index.rst
@@ -2,43 +2,49 @@
 ElasticUtils
 ============
 
-ElasticUtils provides tools to:
+.. _project-details:
 
-* Query ElasticSearch within python
+About ElasticUtils
-* Maintain a single `pyes.ES` object
+==================
-* Test code that is dependent on ElasticSearch
 
+ElasticUtils is a Python library that gives you a Django queryset-like
+API for `elasticsearch <http://elasticsearch.org/>`_ as well as some
+other tools for making it easier to integrate elasticsearch into your
+application.
 
-Project details
+:Code:          https://github.com/mozilla/elasticutils
-===============
+:License:       BSD; see LICENSE file
+:Issues:        https://github.com/mozilla/elasticutils/issues
+:Documentation: http://elasticutils.readthedocs.org/
+:IRC:           #elasticutils on irc.mozilla.org
 
-Code:
-    http://github.com/mozilla/elasticutils
 
-Documentation:
+.. _users-guide:
-    http://elasticutils.rtfd.org
 
-Issue tracker:
+User's Guide
-    https://github.com/mozilla/elasticutils/issues
+============
 
-IRC:
+.. toctree::
-    ``#elasticutils`` on irc.mozilla.org
+   :maxdepth: 1
 
-License:
+   installation
-    BSD 3-clause; see LICENSE file
+   configuration
+   es
+   queries
+   django
+   testing
+   debugging
 
 
-Contents
+Contributor's Guide
-========
+===================
 
 .. toctree::
-  :maxdepth: 2
+   :maxdepth: 1
-
-  installation
-  es
-  django
-  queries
-  testing
-  debugging
 
+   join
+   hacking_howto
+   dev_conventions
+   dev_documentation
+   dev_testing
 
diff --git a/docs/installation.rst b/docs/installation.rst
@@ -4,66 +4,23 @@
 Installation
 ============
 
-Download
+There are a few ways to install ElasticUtils.
---------
 
-Clone it from https://github.com/mozilla/elasticutils .
 
+From PyPI
+=========
 
-Configure
+Do::
----------
 
-`elasticutils` depends on the following settings:
+    $ pip install elasticutils
 
-.. module:: django.conf.settings
 
-.. data:: ES_DISABLED
+From git
+========
 
-    Disables talking to ElasticSearch from your app.  Any method
+Do::
-    wrapped with `es_required` will return and log a warning.  This is
-    useful while developing, so you don't have to have ElasticSearch
-    running.
 
-.. data:: ES_TIMEOUT
+    $ git clone git://github.com/mozilla/elasticutils.git
 
-    Defines the timeout for the `ES` connection.  This defaults to 1 second.
+For other ways to clone, see
-
+`<https://github.com/mozilla/elasticutils>`_.
-.. data:: ES_DUMP_CURL
-
-    If set to a path all the requests that `ElasticUtils` makes will be dumped
-    into the designated file.
-
-    .. note:: Python does not write this file until the process is finished.
-
-
-.. data:: ES_HOSTS
-
-    This is a list of hosts.  In development this will look like::
-
-        ES_HOSTS = ['127.0.0.1:9200']
-
-.. data:: ES_INDEXES
-
-    This is a mapping of doctypes to indexes. A `default` mapping is required
-    for types that don't have a specific index.
-
-    When ElasticUtils queries the index for a model, it derives the doctype
-    from `Model._meta.db_table`.  When you build your indexes and doctypes,
-    make sure to name them after your model db_table.
-
-    Example 1::
-
-        ES_INDEXES = {'default': 'main_index'}
-
-    This only has a default, so ElasticUtils queries will look in `main_index`
-    for all doctypes.
-
-    Example 2::
-
-        ES_INDEXES = {'default': 'main_index',
-                      'splugs': 'splugs_index'}
-
-    Assuming you have a `Splug` model which has a `Splug._meta.db_table`
-    value of `splugs`, then ElasticUtils will run queries for `Splug` in
-    the `splugs_index`.  ElasticUtils will run queries for other models in
-    `main_index` because that's the default.
diff --git a/docs/join.rst b/docs/join.rst
@@ -0,0 +1,32 @@
+==================
+Join this project!
+==================
+
+Interested in working on a Python library for using elasticsearch?
+Interested in using it? Then you should be interested in this project!
+
+
+Want to help?
+=============
+
+Here are things we need help with:
+
+* **fixing bugs listed in the issue tracker**
+
+* **writing tests**
+
+* **writing documentation**: We could use help writing better
+  documentation for ElasticUtils.
+
+* **spreading the word**: Do you know other people who would like this
+  software? If so, tell them about ElasticUtils!
+
+* **project infrastructure**: Is there infrastructure that's missing
+  in this project that would make it easier for you to collaborate? If
+  so, what?
+
+
+Are you thinking, "That list is makes me want to go shopping for bumper
+stickers!" That's ok!  Hop on IRC, say hi and we can go from there!
+
+For project details, see :ref:`project-details`.