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