.. _sphinx:

======
Sphinx
======

Using Sphinx to create documentation.


.. _sphinx_install:

Installing Sphinx
=====================

Create a project folder and :ref:`virtualenv` (remember to activate it) then::

  # Ensure you are in the project folder with the virtualenv activated
  pip install sphinx
  sphinx-quickstart

You can usually accept the defaults unless you have something specific in mind.

Add the following to the conf.py file after extensions::

  source_suffix = {
      '.txt': 'restructuredtext',
      '.rst': 'restructuredtext',
      '.md': 'markdown',
  }


Using Sphinx
============

Create another page with the suffix .rst e.g.

::

  touch sphinx.rst
  
Add information to the page, including a heading underlined by equals signs.

On the index.rst page leave a line space under maxdepth and add the file name. When the HTML files are generated, it will pick up the titles of the pages from the files you list there and create a contents page.

::

  make html


Notes
=====

Headings with a line above and below are optional - only the line below is required.

This is the heading structure I have settled on::

  ==========
  Page title
  ==========

  Heading 1
  =========

  Heading 2
  ---------

The other thing they have on each page at the top to help with linking is::

  .. _page_name:
  
You can link to them with::

  :ref:`page_name`
  
This will insert the title from the other page that is directly under the link marker.

More information can be found at `<http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#internal-and-external-links>`_

::

  `<http://www.python.org/>`_
  OR
  `Python <http://www.python.org/>`_
  
  .. _rst_tutorial:
  LETS YOU LINK USING
  :ref:`rst_tutorial`
  
  A paragraph with `a link`_.
  Underneath the paragraph put:
  .. _a link: http://example.com/
  
Code ``within a line`` can be highlighted: ::

  Here is a ``specific`` word highlighted as code using double backticks.
  
.. note:: `Read the docs`_ recommends saving files as .txt rather than .rst for compatibility.

.. _Read the docs: http://documentation-style-guide-sphinx.readthedocs.org/en/latest/style-guide.html

Notes in a box can be added using::

  .. note:: `Read the docs`_ recommends saving files as .txt rather than .rst for compatibility.
  OR
  .. note:: 
    
    `Read the docs`_ recommends saving files as .txt rather than .rst for compatibility.

.. code-block:: python

  import this
  
`Example website`_ can be referenced::

  .. target-notes::

  .. _`Example website`: http://www.example.com/

.. target-notes::

.. _`Example website`: http://www.example.com/

.. seealso:: ``.. seealso::`` This is a simple **seealso** note.

.. note:: ``.. note::`` This is a **note** box.

Warning box ::

  .. warning:: Remember the space between the directive and the text

.. warning:: ``.. warning::`` Remember the space between the directive and the text

.. image:: ../photoshop/_static/cat-in-hat.jpg
    :width: 200px
    :align: center
    :alt: alternate text