Add custom Table of Contents
============================

The user has the ability to define a custom Table of Contents, in order to highlight 
different aspects of the documentation using ``-index`` argument.

The description file must follow the `Sphinx <https://sphinx-doc-zh.readthedocs.io/en/latest/markup/toctree.html>`_ index file format.
The paths included in the index file must be provided afterwards using ``-attach`` argument.

.. code-block:: rst
    :caption: Custom index.rst file description
    :emphasize-lines: 8,9,10,11
    
    API Specification
    ======================

    .. toctree:: 
       :maxdepth: 5
       :caption: OVERVIEW DOCUMENTATION

       menu/description.md
       menu/features.md
       menu/programming.rst
       menu/timing.rst

    .. toctree:: 
       :maxdepth: 2
       :caption: API DOCUMENTATION
       :titlesonly:

       index-tops.rst
       modules/index-modules.rst
       index-macros.rst

.. code-block:: console

   $ $DVT_HOME/bin/specador.sh ... -index /path/to/index.rst -attach /path/to/menu/dir

.. important:: 

    All the paths specified in index file are relative to the *<output-folder-name>/source* folder, by default **specador_docs/source**. The **-attach** argument simply
    copies the paths under this directory.