getting started
================

A sphinx installation provides you with two command-line tools:

:program:`sphinx-quickstart`
   initiate a sphinx project:

:program:`sphinx-build`
   build the documentation (to html or pdf) from rst


.. _sphinx-quickstart:
.. _root_directory:
.. index:: sphinx-quickstart

:program:`sphinx-quickstart`
------------------------------

At the command-line, type:

.. code-block:: sh

   $ sphinx-quickstart

for an interactive program  which
queries setup options and writes out
a file :ref:`conf_py` in the root directory of your project.
Edit this file by hand afterwards to change configuration as you prefer.

I suggest accepting default locations.

Filenames referenced throughout the documentation are either relative
to the current file (e.g. ``subdirectory/filename``, ``../../filename``), or relative
to this root directory (``/root/subdirectory/../filename``)

You can elect to have sphinx install a :file:`Makefile` 
(linux) or :file:`make.bat` (MS) which provides common
invocations of :command:`sphinx-build`.


Extensions are offered in this setup  - you can elect to include these
now,  or do so later [#]_ :

*  autodoc  - to pull in docstrings from code
*  intersphinx  - to link with other python documentation
*  pngmath or jsmath - to enable latex math-mode in html


.. index:: sphinx-build
.. _sphinx-build:

:program:`sphinx-build`
-----------------------

.. code-block::  sh

   $ man sphinx_build

shows :command:`sphinx-build` :ref:`usage <sphinx_build_manpage>`.


.. code-block:: sh

   $ sphinx-build  -b html -d build/doctrees source build/html

   $ sphinx-build  -b latex -d build/doctrees source build/latex

   $ sphinx-build  -b doctest -d build/doctrees source 

or use the convenience of :command:`make` and the 
:ref:`Makefile` written by
:program:`sphinx-quickstart`:

.. code-block:: bash

      $ make help                      (to see all possibilities)
      $ make html                      (to render docs as html)
      Build finished. The HTML pages are in build/html.

      $ browse build/html/index.html   (to view the html-docs)


.. code-block:: bash

      $ make latex                     (to render docs as tex)
      $ cd build/latex
      $ make all-pdf                   (to process tex file to pdf)

for the pdf, or

.. code-block:: bash

      $ make doctest

to run doctest on the docstrings of your documented code.

In addition, you'll see from the :command:`make help` that you can
also run:

.. code-block:: bash

      $ make linkcheck

to have sphinx check all the links in your documents.

.. rubric:: Footnote

.. [#] by editing the ``extensions`` variable in the file :file:`conf.py`


.. glossary::

   root-directory
      location of the file :file:`conf.py` from the
      :command:`sphinx-quickstart` output.