From 1088b37e70e192d2a279bbfc55d33238f090d72e Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Mon, 11 Oct 2010 20:02:04 -0400 Subject: more docs --- docs/README | 41 +++++++++++++++++++++++++++++------------ 1 file changed, 29 insertions(+), 12 deletions(-) (limited to 'docs/README') diff --git a/docs/README b/docs/README index 8556dd2..174f55a 100644 --- a/docs/README +++ b/docs/README @@ -1,22 +1,36 @@ -This directory contains the Sphinx documentation for libmaple. You -can generate HTML documentation using the Makefile if you have make, -or using make.bat from Windows. +This directory contains the Sphinx documentation for libmaple, as well +as a Doxygen configuration file; we turn Doxygen XML output into +Sphinx documentation. You can generate HTML documentation using the +Makefile if you have make, or using make.bat from Windows. -For the impatient, you can build the HTML docs with (on Unix): +You need a recent-ish version of doxygen in your PATH: + + http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc + +For the Doxygen-to-Sphinx bridge, we rely on a project called Breathe, +by Michael Jones. You must clone the breathe repository and set an +environment variable BREATHE_HOME to be able to build the +documentation. Something like this on bash: + + $ git clone http://github.com/michaeljones/breathe.git + $ export BREATHE_HOME /path/to/breathe/repo/ + +You can now build the HTML docs with (on Unix): $ sudo easy_install -U Sphinx $ make html -Which will produce HTML documentation in build/html. +Which will produce Doxygen documentation in doxygen/xml, and HTML +documentation (this is what you want to look at) in build/html. All of the documentation itself lives in source/. The directory source/_static is for static content like style sheets; -source/_templates contains Sphinx templates. +source/_templates contains Sphinx templates (or, it would if we had +any). -The documentation is written in reStructuredText (reST); it's a Python -thing that they use to produce the docs at python.org (which are -beautiful, if you've never seen them). You can read more about Sphinx -here: +The docs are written in reStructuredText (reST); it's a Python thing +that they use to produce the docs at python.org (which are beautiful, +if you've never seen them). You can read more about Sphinx here: http://sphinx.pocoo.org/tutorial.html @@ -24,5 +38,8 @@ Specific information on documenting C and C++ is available here: http://sphinx.pocoo.org/domains.html -The file source/conf.py is an autogenerated configuration file; you -can read it yourself. +You can view the reST source for any generated page of documentation +by clicking the "Show Source" link in the sidebar. + +The file source/conf.py is the Sphinx configuration file; you can go +read it for more information about our setup. -- cgit v1.2.3