blob: a724ddcafeb1bb5b54ff1de1891323cc8098dd68 (
plain)
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
|
.. _faq:
Sphinx FAQ
==========
This is a list of Frequently Asked Questions about Sphinx. Feel free to
suggest new entries!
How do I...
-----------
... get section numbers?
They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to
the :dir:`toctree` directive where you want to start numbering.
... customize the look of the built HTML files?
Use themes, see :doc:`theming`.
... add global substitutions or includes?
Add them in the :confval:`rst_epilog` config value.
... write my own extension?
See the :ref:`extension tutorial <exttut>`.
... convert from my existing docs using MoinMoin markup?
The easiest way is to convert to xhtml, then convert `xhtml to reST`_. You'll
still need to mark up classes and such, but the headings and code examples
come through cleanly.
Using Sphinx with...
--------------------
Epydoc
There's a third-party extension providing an `api role`_ which refers to
Epydoc's API docs for a given identifier.
Doxygen
Michael Jones is developing a reST/Sphinx bridge to doxygen called `breathe
<http://github.com/michaeljones/breathe/tree/master>`_.
SCons
Glenn Hutchings has written a SCons build script to build Sphinx
documentation; it is hosted here: http://bitbucket.org/zondo/sphinx-scons
github pages
You can use `Michael Jones' sphinx-to-github tool
<http://github.com/michaeljones/sphinx-to-github/tree/master>`_ to prepare
Sphinx HTML output.
.. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
|
