.. _configuring sphinx:

####################
Sphinx Configuration
####################

Configuration (sphinx)
======================

Extensions
----------

When using the eclipse ReST editor to create the project, the `sphinx todo`_
extension will be enabled by default.  Otherwise enable it:

.. code-block:: shell

   ~/documentation $ grep extensions source/conf.py
   extensions = ['sphinx.ext.todo']

Theme
-----

To set a theme (using *groundwork* as the default):

.. code-block:: shell

   ~/documentation $ grep theme source/conf.py
   html_theme = u'groundwork'

To install a theme:

.. code-block:: shell

   ~/documentation $ pip install --user groundwork-sphinx-theme

.. seealso::
   Other themes are avaialable, see the official documentation, 
   `sphinx html theming <https://www.sphinx-doc.org/en/master/usage/theming.html>`_


The **todo** extension

Adding sections like the following

.. code-block::

    .. todo:: Create directory: 'src/main/python/docs/ext/todo'

       [ ] make directory 'src/main/python/docs/ext/todo'

Will direct sphinx to create a todo list [todoslist]_


.. [todoslist] A todo list

.. todo::  create directory

   [ ] src/main/python/docs/ext/todo

.. _sphinx todo: https://www.sphinx-doc.org/es/master/usage/extensions/todo.html