.. _about:

About this Website
==================

This website is created using `Sphinx <http://sphinx.pocoo.org/>`_.

The source of this website is under version control at
https://github.com/mozilla-services/docs. (It also lives in a Mercurial
repository at https://hg.mozilla.org/services/docs. However, the GitHub
repository is favored as it is simpler for non-Mozilla people to contribute.)

If you want to change the content of this website, changes will need to be
made to the *master* branch of the aforementioned Git repository.

This can be done one of several ways:

- Fork the repository on GitHub and create a pull request.
- Send a patch to the `services-dev@mozilla.org <https://mail.mozilla.org/listinfo/services-dev>`_
  mailing list.
- Create a Bugzilla issue at https://bugzilla.mozilla.org/ under the **Mozilla
  Services** product for the component the docs impact.

Generating Documentation
------------------------

To generate the docs from source, you'll need to obtain Sphinx along with some
extensions.

Assuming you are using Virtualenv::

   $ virtualenv sphinx-env
   $ source sphinx-env/bin/activate
   # You are now in the fresh virtualenv for Sphinx.

   # Install dependencies.
   $ pip install sphinx sphinxcontrib-seqdiag

   # Build HTML docs.
   $ make html

By default, the Makefile looks for *sphinx-build* in your *PATH*. If you have
*sphinx-build* elsewhere, just pass the path to the Makefile::

   $ make html SPHINXBUILD=/path/to/sphinx-build

Directory Structure
-------------------

The source is located in the :file:`source` directory and contains:

- **howtos**: a directory with How Tos
- **server-devguide**: server development guide, guidelines, how to release a
  server app etc.
- one directory per Server application (**reg**, **sreg**, etc.)

Update process
--------------

The website is located in a svn repository which gets regular snapshots of
the HTML structure generated by Sphinx. This should run automatically (i.e.
changes checked into GitHub should automatically propagate to the official web
site). If this does not happen, please send a message to the
services-dev@mozilla.org mailing list and request an update.