[llvm-commits] [lld] r154228 - in /lld/trunk/docs: conf.py contents.rst development.rst sphinx_intro.rst
Daniel Dunbar
daniel at zuster.org
Fri Apr 6 16:47:35 PDT 2012
Author: ddunbar
Date: Fri Apr 6 18:47:34 2012
New Revision: 154228
URL: http://llvm.org/viewvc/llvm-project?rev=154228&view=rev
Log:
[docs] Start a development guide, and write an introduction to Sphinx based
documentation.
Added:
lld/trunk/docs/development.rst
lld/trunk/docs/sphinx_intro.rst
Modified:
lld/trunk/docs/conf.py
lld/trunk/docs/contents.rst
Modified: lld/trunk/docs/conf.py
URL: http://llvm.org/viewvc/llvm-project/lld/trunk/docs/conf.py?rev=154228&r1=154227&r2=154228&view=diff
==============================================================================
--- lld/trunk/docs/conf.py (original)
+++ lld/trunk/docs/conf.py Fri Apr 6 18:47:34 2012
@@ -146,7 +146,7 @@
#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 @@
# 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
Modified: lld/trunk/docs/contents.rst
URL: http://llvm.org/viewvc/llvm-project/lld/trunk/docs/contents.rst?rev=154228&r1=154227&r2=154228&view=diff
==============================================================================
--- lld/trunk/docs/contents.rst (original)
+++ lld/trunk/docs/contents.rst Fri Apr 6 18:47:34 2012
@@ -8,6 +8,8 @@
intro
design
+ development
+ sphinx_intro
Indices and tables
==================
Added: lld/trunk/docs/development.rst
URL: http://llvm.org/viewvc/llvm-project/lld/trunk/docs/development.rst?rev=154228&view=auto
==============================================================================
--- lld/trunk/docs/development.rst (added)
+++ lld/trunk/docs/development.rst Fri Apr 6 18:47:34 2012
@@ -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`.
Added: lld/trunk/docs/sphinx_intro.rst
URL: http://llvm.org/viewvc/llvm-project/lld/trunk/docs/sphinx_intro.rst?rev=154228&view=auto
==============================================================================
--- lld/trunk/docs/sphinx_intro.rst (added)
+++ lld/trunk/docs/sphinx_intro.rst Fri Apr 6 18:47:34 2012
@@ -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.
More information about the llvm-commits
mailing list