contrib/llvm/tools/lld/docs/sphinx_intro.rst

   1 .. _sphinx_intro:
   2
   3 Sphinx Introduction for LLVM Developers
   4 =======================================
   5
   6 This document is intended as a short and simple introduction to the Sphinx
   7 documentation generation system for LLVM developers.
   8
   9 Quickstart
  10 ----------
  11
  12 To 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
  23 Installing Sphinx
  24 ~~~~~~~~~~~~~~~~~
  25
  26 You should be able to install Sphinx using the standard Python package
  27 installation 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
  36 If you do not have root access (or otherwise want to avoid installing Sphinx in
  37 system directories) see the section on :ref:`installing_sphinx_in_a_venv` .
  38
  39 If you do not have the ``easy_install`` tool on your system, you should be able
  40 to 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
  57 Building the documentation
  58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  59
  60 In order to build the documentation need to add ``-DLLVM_ENABLE_SPHINX=ON`` to
  61 your ``cmake`` command.  Once you do this you can build the docs using
  62 ``docs-lld-html`` build (``ninja`` or ``make``) target.
  63
  64 That build target will invoke ``sphinx-build`` with the appropriate options for
  65 the project, and generate the HTML documentation in a ``tools/lld/docs/html``
  66 subdirectory.
  67
  68 .. _writing_documentation:
  69
  70 Writing documentation
  71 ~~~~~~~~~~~~~~~~~~~~~
  72
  73 The documentation itself is written in the reStructuredText (ReST) format, and
  74 Sphinx defines additional tags to support features like cross-referencing.
  75
  76 The ReST format itself is organized around documents mostly being readable
  77 plaintext documents. You should generally be able to write new documentation
  78 easily just by following the style of the existing documentation.
  79
  80 If you want to understand the formatting of the documents more, the best place
  81 to start is Sphinx's own `ReST Primer <http://sphinx.pocoo.org/rest.html>`_.
  82
  83
  84 Learning More
  85 -------------
  86
  87 If you want to learn more about the Sphinx system, the best place to start is
  88 the Sphinx documentation itself, available `here
  89 <http://sphinx.pocoo.org/contents.html>`_.
  90
  91
  92 .. _installing_sphinx_in_a_venv:
  93
  94 Installing Sphinx in a Virtual Environment
  95 ------------------------------------------
  96
  97 Most Python developers prefer to work with tools inside a *virtualenv* (virtual
  98 environment) instance, which functions as an application sandbox. This avoids
  99 polluting your system installation with different packages used by various
 100 projects (and ensures that dependencies for different packages don't conflict
 101 with one another). Of course, you need to first have the virtualenv software
 102 itself which generally would be installed at the system level::
 103
 104   $ sudo easy_install virtualenv
 105
 106 but after that you no longer need to install additional packages in the system
 107 directories.
 108
 109 Once you have the *virtualenv* tool itself installed, you can create a
 110 virtualenv 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
 120 and from now on you can "activate" the *virtualenv* using::
 121
 122   $ source ~/my-sphinx-install/bin/activate
 123
 124 which will change your PATH to ensure the sphinx-build tool from inside the
 125 virtual environment will be used. See the `virtualenv website
 126 <http://www.virtualenv.org/en/latest/index.html>`_ for more information on using
 127 virtual environments.