= Help Writing Bitten Documentation =

Bitten distribution is accompanied by nice User Manual. You may see a plain reflection of it on [wiki:Documentation/index.html] pages. If you reading this then you already know that these pages are immutable, at least it is not possible to edit them from Wiki. It is because Trac is reading them directly from SVN repository using an `[[Include()]]` macro. Typical User Manual page source looks like this:
{{{
[[Title(Installation)]]
[[Include(trunk/doc/install.txt)]]

----
See also: [wiki:Documentation]
}}}

These wiki pages are created manually and set to read-only, updatable only by Bitten developers.

If you need to propose a change - you should be able to checkout docs from SVN, edit sources in reStructuredText format (similar to Wiki), rebuild them to see the result of your changes and attach the patch to a [/newticket new ticket] (or open a discussion on Bitten MailingList).

=== Checkout ===

Just checkout Bitten. Usually [source:trunk trunk/], but any recent [source:tags tags/] or [source:branches/] is usually also fine. For example:
{{{
svn checkout http://svn.edgewall.org/repos/bitten/trunk bitten-trunk
}}}
will download sources into a ''bitten-trunk'' directory.

=== Building Docs ===

Prerequisites:
 1. `docutils` (usually installed by Trac development setup anyway)
 2. `epydoc`

Build:
 4. Run: `python setup.py build_doc`
 5. Open `doc/index.html` in a browser to verify result

=== Making a change ===

Just edit *.txt files, which are in [http://docutils.sourceforge.net/rst.html reStructuredText] format and rerun `python setup.py build_doc` to get the edits into html. If you are ready, make a patch file:
{{{
svn diff > documentation.diff
}}}

=== Adding a new page ===

Things to remember when adding a new page to documentation:
 1. Add the page to `index.txt` so that users can find the page.
 2. Add the file to repository using `text/x-rst` set for `svn:mime-type`.
 3. Test the file using `setup.py build_doc` before committing.
 4. Make a `Documentation/<newpage>.html` wiki page following the `[[Include]]` macro pattern described above.

See also all [query:status!=closed&component=Documentation open documentation tickets].