diff options
Diffstat (limited to 'docs/README')
-rw-r--r-- | docs/README | 98 |
1 files changed, 0 insertions, 98 deletions
diff --git a/docs/README b/docs/README deleted file mode 100644 index 7a50a54..0000000 --- a/docs/README +++ /dev/null @@ -1,98 +0,0 @@ -This directory contains source files used to generate libmaple's -documentation. - -The generated documentation for the latest libmaple release is -available online in HTML form at http://leaflabs.com/docs/. The web -interface is the recommended way for users to read the documentation. - -This file contains instructions for generating the HTML files. - -About the Documentation ------------------------ - -The docs are written in Sphinx's extensions to reStructuredText -(reST). You can read more about Sphinx here: - - http://sphinx.pocoo.org/tutorial.html - -Much of the documentation is pulled out of the libmaple source code; -we use Doxygen XML output into Sphinx documentation. You can read -more about Doxygen here: - - http://doxygen.org - -We use a Sphinx plugin called Breathe to parse Doxygen's XML output -into a form usable by Sphinx. You can read more about Breathe here: - - http://michaeljones.github.com/breathe/ - -Documentation Build Steps -------------------------- - -You first need to produce Doxygen XML output, then you can generate -the HTML documentation. - -1. You need a recent-ish version of Doxygen in your PATH: - - http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc - -2. Install Breathe, which does Doxygen-to-Sphinx conversion: - - Read/write version (for LeafLabs developers): - - $ git clone git@github.com:leaflabs/breathe.git - - Read-only version (for non-LeafLabs developers): - - $ git clone git://github.com/leaflabs/breathe.git - - After that's done, set an environment variable BREATHE_HOME to - point to where you downloaded it. Something like this on bash: - - $ export BREATHE_HOME=/path/to/breathe/repo/ - - (You'll want to put this in your shell startup script). - -3. Install Sphinx. - - From source or .egg: - - http://pypi.python.org/pypi/Sphinx#downloads - - Via easy_install: - - $ sudo easy_install -U Sphinx - - You need Sphinx version >= 1.0.6. - -4. Before the first time you run Sphinx (and any time the Doxygen - comments in the libmaple source code are changed), you'll need to - build the Doxygen XML output: - - $ cd libmaple/docs/source - $ doxygen - -5. Finally, you can build the documentation: - - $ make html - - On Windows, use the batch file make.bat instead. - -Reading and Modifying the Documentation ---------------------------------------- - -Just point your web browser at the file - - /docs/build/html/index.html - -It corresponds to the Sphinx file - - /docs/source/index.rst - -The file /docs/source/conf.py is the Sphinx configuration file; you -can go read it for more information about our setup. - -All of the documentation which isn't pulled out of source code -comments lives in /docs/source/. The directory /docs/source/_static/ -is for static content (like style sheets); /docs/source/_templates/ -contains Sphinx templates. |