.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   nspecific language governing permissions and limitations
   under the License.

Building documentation
======================

Build the documentation with ``make doc``.

If you have an older verbsion of cmake, the documentation may be built when you
do ``make all``. If so you can disable documentation build with

::

    cmake -DBUILD_DOCS=OFF

You need the following tools to build the documentation:

- python-sphinx (1.1.3) for book and man pages (requires python-docutils)
- doxygen (1.8) for API documentation.
- graphviz (2.34) for ``dot`` program needed to include diagrams in API documentation.

The versions above are known to work, earlier versions may or may not.

Writing documentation
=====================

Documentation is written in `reStructuedText <http://docutils.sourceforge.net/rst.html>`__

All rst and html format documentation is installed in the share/doc directory.
Man pages are also installed in the standard share/man locations.

The `dispatch web site <http://qpid.apache.org/components/dispatch-router>`__
has pre-generated documentation for each release and a random snapshot of the
trunk.

Documentation sub-directories:

-  ``book/``: Book-format documentation.
-  ``man/``: Unix man pages.
-  ``api/``: Generated API documentation.
-  ``notes/``: Developer notes: project information, design notes, or
   anything else that's primarily of developer interest. These are not
   installed.

Editing the book.
=================

Most chapters of the book are restructuredText_ files, you can edit them with
any text editor. See the `quick reference`_ for a handy guide to syntax.

Some chapters are generated by python scripts rather than being simple
source files. For example ``schema.md`` is generated by ``schema_md.py``
from the documentation strings in the management schema
``qdrouterd.json``.

.. _restructuredText: http://docutils.sourceforge.net/rst.html
.. _`quick reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html