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