Permalink
Browse files

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.
  • Loading branch information...
1 parent 370f2c8 commit 5d96df7c3fe069dea00ba0e396ad5bde358113be @willkg willkg committed Jun 8, 2012
View
@@ -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.
View
@@ -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>`_.
View
@@ -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
View
@@ -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.
View
@@ -2,13 +2,14 @@
Django Model Integration
========================
-Django Models and ElasticSearch indices make a natural fit.
-It would be terribly useful if a Django Model knew how to add and remove itself
-from ElasticSearch.
-This is where the :class:`elasticutils.models.SearchMixin` comes in.
+Django Models and ElasticSearch indices make a natural fit. It would
+be terribly useful if a Django Model knew how to add and remove itself
+from ElasticSearch. This is where the
+:class:`elasticutils.models.SearchMixin` comes in.
-You can then utilize things such as :func:`~elasticutils.tasks.index_objects` to
-automatically index all new items.
+You can then utilize things such as
+:func:`~elasticutils.tasks.index_objects` to automatically index all
+new items.
.. autoclass:: elasticutils.models.SearchMixin
:members:
View
@@ -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.
View
@@ -2,43 +2,49 @@
ElasticUtils
============
-ElasticUtils provides tools to:
+.. _project-details:
-* Query ElasticSearch within python
-* Maintain a single `pyes.ES` object
-* Test code that is dependent on ElasticSearch
+About ElasticUtils
+==================
+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:
- http://elasticutils.rtfd.org
+.. _users-guide:
-Issue tracker:
- https://github.com/mozilla/elasticutils/issues
+User's Guide
+============
-IRC:
- ``#elasticutils`` on irc.mozilla.org
+.. toctree::
+ :maxdepth: 1
-License:
- BSD 3-clause; see LICENSE file
+ installation
+ configuration
+ es
+ queries
+ django
+ testing
+ debugging
-Contents
-========
+Contributor's Guide
+===================
.. toctree::
- :maxdepth: 2
-
- installation
- es
- django
- queries
- testing
- debugging
+ :maxdepth: 1
+ join
+ hacking_howto
+ dev_conventions
+ dev_documentation
+ dev_testing
View
@@ -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
- wrapped with `es_required` will return and log a warning. This is
- useful while developing, so you don't have to have ElasticSearch
- running.
+Do::
-.. data:: ES_TIMEOUT
+ $ git clone git://github.com/mozilla/elasticutils.git
- Defines the timeout for the `ES` connection. This defaults to 1 second.
-
-.. 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.
+For other ways to clone, see
+`<https://github.com/mozilla/elasticutils>`_.
View
@@ -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`.
Oops, something went wrong.

0 comments on commit 5d96df7

Please sign in to comment.