| Date: | 2011-01-04 |
|---|
Contents
Manticore aims to be a blueprint for a documentation system based on Sphinx_. Its main intention is to have an environment at your fingertips which supports rendering reStructuredText_ documentation spread across multiple git- or subversion-repositories.
Manticore's focus is on documentation locality (keep all your .rst files inside the code repository they belong to), distributedness (you have some or even a lot of repositories) and aggregation (use Sphinx_'s cross-referencing features to interlink between documentation of different projects or artefacts). This is achieved by standing on the shoulders of giants like git_, buildout_ and Sphinx_.
Manticore uses buildout_ along with its zerokspot.recipe.git_ and infrae.subversion_ recipes to get hold of all configured repository trees and runs the fine Sphinx_ documentation generator across them turning the reStructuredText_ documentation into beautiful static html.
This naturally encourages developers and architects to write documentation in a very collaborative and productive manner, even offline as there is no server or internet access required. Everything is git-based and the documentation sources are hosted inside the project repository you are already working on - no context switch required. :-)
On top of that, Manticore adds some nice-to-have functionality through Sphinx_ extensions and regular Python_ code. Take a look at the :ref:`manticore-features` for details.
- Include documentation from docstrings.
- Add links to highlighted source code.
- Support for todo items.
- Include content based on configuration.
- Add Graphviz graphs.
- Markup to shorten external links.
- Generates a RSS feed of your site containing all articles that occur therein,indexed by document date. Date is supplied as a standard document metadata field.
.. seealso:: :ref:`manticore-latest-edits` - sphinxcontrib-sdedit_, see also: `sdedit extension README`_Insert sequence diagrams in your Sphinx_ document.The diagrams can be authored using the `Quick Sequence Diagram Editor`_ aka. sdedit_ editor.
- sphinxcontrib-seqdiag_ based on seqdiag_Insert sequence diagrams in your Sphinx_ document.
- sphinxcontrib-blockdiag_ based on blockdiag_Insert block diagrams in your Sphinx_ document.
- sphinxcontrib-nwdiag_ based on nwdiag_Insert network diagrams into your Sphinx_ document.
zt.manticore.ext.changes- Automatic reStructuredText_ generation of aggregated, chronological changes across all projects
- Visualize changes using the fine `SIMILE Timeline Widget`_
zt.manticore.ext.gourceSource code repository visualization using Gource_.zt.manticore.ext.bugseverywhereAutomatic html generation of BugsEverywhere_ issues from git repositories.zt.manticore.ext.laig"lightweight artifact interconnection grapher" based on Graphviz_
sudo port install py-virtualenv py-docutils gnuplot
yum -y install openjpeg-devel zlib-devel freetype-devel gnuplot
Get a copy of the source tree:
git clone git@git.example.net:documentation/meta.git
Run bootstrap and buildout as denoted below:
virtualenv-2.7 --no-site-packages .venv27 . .venv27/bin/activate pip install setuptools==0.7.2 python bootstrap.py bin/buildout
To update and build all resources and artifacts, run:
make
To run sphinx to generate the html output only, use:
make html
The html output path is ./var/sphinx, the root page is
./var/sphinx/index.html. To open it, use e.g.:
open ./var/sphinx/index.html
TeX is required to generate Latex and PDF output:
sudo port install texlive texlive-latex-extra texlive-latex-recommended texlive-fonts-recommended
then run:
make pdf
To open it, use e.g.:
open ./var/latex/index.pdf
Just add a new section to buildout.cfg, like:
For git repositories:
[foobar] recipe = zerokspot.recipe.git repository = git://git.example.net/three-investigators/foobar.git newest = true
Warning
Be aware that these git uris are used by everyone rendering the documentation, so you should prefer addresses using anonymous read-only access respectively uris that are username-agnostic. The main reason is not every contributor might have read-write access to all repositories listed.
A solution could be to nail the username via ~/.ssh/config, e.g.:
Host git.example.net
User hotzenplotz
For subversion repositories:
[acme] recipe = infrae.subversion urls = https://svn.example.net/svn/three-investigators/acme/trunk/ .
Make sure the new section will be built by default by adding the section name
to the variable parts in section [buildout]:
[buildout]
parts =
foobar
acme
# ...
Add your documents to (e.g.) src/index.rst.
Use title from document (e.g.):
- :doc:`artefacts/foobar/docs/index`
Use custom title (e.g.):
- :doc:`About Foobar <artefacts/foobar/docs/index>`
Note
Files must have the .rst-suffix to be scanned and found by Sphinx.
However, when linking into the document tree, just use the filename without suffix.
Inside your reStructuredText documentation, place a reference anchor:
.. _my-reference:
... and then link to it using:
:ref:`my-reference`
By default, this will use the referenced section name as link title. To tweak the link title, use:
:ref:`Custom link title <my-reference>`
You may just want to start a local Python webserver:
cd var/sphinx; python -m SimpleHTTPServer 8668; cd - open http://localhost:8668/
Serve via Nginx...
Install:
make nginx
Serve:
bin/nginx start open http://localhost:8668/
Stop nginx again:
bin/nginx stop