README.rst 2.21 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
dx-docs-template
===============

A template configuration for generating sphinx docs for dx projects
-------------------------------------------------------------------

Features
^^^^^^^^

* Separate ``source`` and ``build`` directories.
* Expanded ``Makefile`` that generates automatically API docs
  based on local packages.

14 15 16
Checkout the `live demo <https://d-e.gitlab.io/dx-docs-template>`_ of this
template.

17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
Using the template
------------------

#. Copy the template into your project::

      $ git clone <this-repo> path/to/docs/
      $ make -C path/to/docs/ clean-repo

#. Configure CI for your gitlab project [optional]::

      $ make -C path/to/docs/ gitlab-ci

   This essentially moves the required ``.gitlab-ci.yml`` to the
   root level of your repository. Alternatively, you can explicitly
   define the path to ``.gitlab-ci.yml`` in your project settings.

33 34 35
   Don't forget to override ``DOCSPATH`` and ``MODPATH`` in ``.gitlab-ci.yml``:

   * ``DOCSPATH`` should be assigned the value of the path you cloned the repository
36
     into.
37
   * ``MODPATH`` should be assinged the value of the path of the python-package
38
     to be documented **relative** to the ``DOCSPATH``.
39 40 41 42 43 44 45 46 47 48 49

   By default CI is configured to run only when a tag is created.

#. Set configuration options in ``path/to/docs/source/conf.py``.

#. Add content in ``path/to/docs/source/chapters/``.

#. Modify ``path/to/docs/source/index.rst`` accordingly.

#. Create API docs for your package::

50 51 52 53
      $ make MODPATH=<package-path> -C path/to/docs/ apidoc

   where ``<package-path>`` is the path of the package **relative**
   to ``path/to/docs``.
54 55 56 57 58 59 60 61 62

#. Build documentation::

      $ make -C path/to/docs/ html

.. hint::

   Of course, the last two commands can be combined as follows::

63
      $ make MODPATH=<package-path> -C path/to/docs/ apidoc html
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78

   Precedence of ``apidoc`` over the ``html`` rule is important though.

License
-------

This template is published under the `MIT LICENSE <LICENSE>`_.

Credits
-------

* The default theme is `Alabaster <https://github.com/bitprophet/alabaster>`_.
* The skeleton is based on an automatically generated structure of files
  through ``sphinx-quickstart``. See `Sphinx docs <http://www.sphinx-doc.org>`_
  for more details.