1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
.. _sphinx_intro:
Sphinx Introduction for LLVM Developers
=======================================
This document is intended as a short and simple introduction to the Sphinx
documentation generation system for LLVM developers.
Quickstart
----------
To get started writing documentation, you will need to:
1. Have the Sphinx tools :ref:`installed <installing_sphinx>`.
2. Understand how to :ref:`build the documentation
<building_the_documentation>`.
3. Start :ref:`writing documentation <writing_documentation>`!
.. _installing_sphinx:
Installing Sphinx
~~~~~~~~~~~~~~~~~
You should be able to install Sphinx using the standard Python package
installation tool ``easy_install``, as follows::
$ sudo easy_install sphinx
Searching for sphinx
Reading http://pypi.python.org/simple/sphinx/
Reading http://sphinx.pocoo.org/
Best match: Sphinx 1.1.3
... more lines here ..
If you do not have root access (or otherwise want to avoid installing Sphinx in
system directories) see the section on :ref:`installing_sphinx_in_a_venv` .
If you do not have the ``easy_install`` tool on your system, you should be able
to install it using:
Linux
Use your distributions standard package managament tool to install it, i.e.,
``apt-get install easy_install`` or ``yum install easy_install``.
Mac OS X
All modern Mac OS X systems come with ``easy_install`` as part of the base
system.
Windows
See the `setuptools <http://pypi.python.org/pypi/setuptools>`_ package web
page for instructions.
.. _building_the_documentation:
Building the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to build the documentation, all you should need to do is change to the
``docs`` directory and invoke make as follows::
$ cd path/to/project/docs
$ make html
Note that on Windows there is a ``make.bat`` command in the docs directory which
supplies the same interface as the ``Makefile``.
That command will invoke ``sphinx-build`` with the appropriate options for the
project, and generate the HTML documentation in a ``_build`` subdirectory. You
can browse it starting from the index page by visiting
``_build/html/index.html``.
Sphinx supports a wide variety of generation formats (including LaTeX, man
pages, and plain text). The ``Makefile`` includes a number of convenience
targets for invoking ``sphinx-build`` appropriately, the common ones are:
make html
Generate the HTML output.
make latexpdf
Generate LaTeX documentation and convert to a PDF.
make man
Generate man pages.
.. _writing_documentation:
Writing documentation
~~~~~~~~~~~~~~~~~~~~~
The documentation itself is written in the reStructuredText (ReST) format, and Sphinx
defines additional tags to support features like cross-referencing.
The ReST format itself is organized around documents mostly being readable
plaintext documents. You should generally be able to write new documentation
easily just by following the style of the existing documentation.
If you want to understand the formatting of the documents more, the best place
to start is Sphinx's own `ReST Primer <http://sphinx.pocoo.org/rest.html>`_.
Learning More
-------------
If you want to learn more about the Sphinx system, the best place to start is
the Sphinx documentation itself, available `here
<http://sphinx.pocoo.org/contents.html>`_.
.. _installing_sphinx_in_a_venv:
Installing Sphinx in a Virtual Environment
------------------------------------------
Most Python developers prefer to work with tools inside a *virtualenv* (virtual
environment) instance, which functions as an application sandbox. This avoids
polluting your system installation with different packages used by various
projects (and ensures that dependencies for different packages don't conflict
with one another). Of course, you need to first have the virtualenv software
itself which generally would be installed at the system level::
$ sudo easy_install virtualenv
but after that you no longer need to install additional packages in the system
directories.
Once you have the *virtualenv* tool itself installed, you can create a
virtualenv for Sphinx using::
$ virtualenv ~/my-sphinx-install
New python executable in /Users/dummy/my-sphinx-install/bin/python
Installing setuptools............done.
Installing pip...............done.
$ ~/my-sphinx-install/bin/easy_install sphinx
... install messages here ...
and from now on you can "activate" the *virtualenv* using::
$ source ~/my-sphinx-install/bin/activate
which will change your PATH to ensure the sphinx-build tool from inside the
virtual environment will be used. See the `virtualenv website
<http://www.virtualenv.org/en/latest/index.html>`_ for more information on using
virtual environments.
|
