Examples
========

Example documentation structure
-------------------------------

Here is an example structure for the documentation of a complex command with many subcommands.
You are free to use any structure, but this may be a good starting point.

File "index.rst":

.. code:: rst

   .. toctree::
      :maxdepth: 2

      cmd

File "cmd.rst":

.. code:: rst

   Command line utilities
   **********************

   .. toctree::
      :maxdepth: 1

      cmd_main
      cmd_subcommand


File "cmd_main.rst":

.. code:: rst

   Fancytool command
   ***********************

   .. argparse::
      :module: my.module
      :func: my_func_that_returns_a_parser
      :prog: fancytool

      subcommand
           Here we add a reference to subcommand, to simplify navigation.
           See :doc:`cmd_subcommand`


File "cmd_subcommand.rst":

.. code:: rst

   Subcommand command
   ***********************

   .. argparse::
      :module: my.module
      :func: my_func_that_return_parser
      :prog: fancytool
      :path: subcommand


Source of example file
----------------------

This file will be used in all generated examples.

.. literalinclude:: ../test/sample.py
   :language: python


Generated sample 1 - command with subcommands
---------------------------------------------

Directive
~~~~~~~~~

Source:

.. code:: rst

   .. argparse::
      :filename: ../test/sample.py
      :func: parser
      :prog: sample

Output
~~~~~~

.. argparse::
    :filename: ../test/sample.py
    :func: parser
    :prog: sample


Generated sample 2 - subcommand
-------------------------------

Directive
~~~~~~~~~

Source:

.. code:: rst

   .. argparse::
      :filename: ../test/sample.py
      :func: parser
      :prog: sample
      :path: game

Output
~~~~~~

.. argparse::
   :filename: ../test/sample.py
   :func: parser
   :prog: sample
   :path: game
