[docs] Start a development guide, and write an introduction to Sphinx based

documentation.

llvm-svn: 154228

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

lld/docs/contents.rst

@@ -8,6 +8,8 @@ Contents
 
    intro
    design
+   development
+   sphinx_intro
 
 Indices and tables
 ==================

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`.

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.