| .. 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 |