diff options
| -rw-r--r-- | lld/docs/conf.py | 8 | ||||
| -rw-r--r-- | lld/docs/contents.rst | 2 | ||||
| -rw-r--r-- | lld/docs/development.rst | 13 | ||||
| -rw-r--r-- | lld/docs/sphinx_intro.rst | 143 |
4 files changed, 165 insertions, 1 deletions
diff --git a/lld/docs/conf.py b/lld/docs/conf.py index e1055beec88..00c017f1704 100644 --- a/lld/docs/conf.py +++ b/lld/docs/conf.py @@ -146,7 +146,7 @@ html_additional_pages = {'index': 'index.html'} #html_split_index = False # If true, links to the reST sources are added to the pages. -html_show_sourcelink = False +html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True @@ -243,3 +243,9 @@ texinfo_documents = [ # FIXME: Define intersphinx configration. intersphinx_mapping = {} + + +# -- Options for extensions ---------------------------------------------------- + +# Enable this if you want TODOs to show up in the generated documentation. +#todo_include_todos = False diff --git a/lld/docs/contents.rst b/lld/docs/contents.rst index fa998dad8fb..4959a679596 100644 --- a/lld/docs/contents.rst +++ b/lld/docs/contents.rst @@ -8,6 +8,8 @@ Contents intro design + development + sphinx_intro Indices and tables ================== diff --git a/lld/docs/development.rst b/lld/docs/development.rst new file mode 100644 index 00000000000..2b12e38ff60 --- /dev/null +++ b/lld/docs/development.rst @@ -0,0 +1,13 @@ +.. _development: + +Development +=========== + +lld is developed as part of the `LLVM <http://llvm.org>`_ project. + +.. todo:: Write "getting started" style instructions for developers. + +The project documentation is written in reStructuredText and generated using the +`Sphinx <http://sphinx.pocoo.org/>`_ documentation generator. For more +information on writing documentation for the project, see the +:ref:`sphinx_intro`. diff --git a/lld/docs/sphinx_intro.rst b/lld/docs/sphinx_intro.rst new file mode 100644 index 00000000000..9a8b289b669 --- /dev/null +++ b/lld/docs/sphinx_intro.rst @@ -0,0 +1,143 @@ +.. _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 + +which 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. + + latexpdf + Generate LaTeX documentation and convert to a PDF. + + 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. |
