User Guide

Configuration

In conf.py add the Sphinx extension sphinxinvoke.ext to the extensions.

For example:

extensions = ['sphinxinvoke.ext']

Usage in reST source

The directive has the following options:

• module – module.path.to.invoke.tasks
• prog – the name of the program for tasks

For example provided Example tasks is the module sphinxinvoke.exampletasks, then the invoke command line reference for the tasks can be documented in the following fashion:

.. Copyright (C) 2019, Nokia

Command line interface
======================

.. this requires sphinx-invoke extension package

.. invoke::
   :module: sphinxinvoke.exampletasks
   :prog: program

Example tasks

from __future__ import print_function
from invoke import task  # pylint: disable=import-error


__copyright__ = 'Copyright (C) 2019, Nokia'


@task
def task_a(arga):
    """Task a description.

    Args:
        arga:   arga description
    """
    print(arga)


@task
def task_b(argb):
    """Task b description.

    Args:
        argb:   argb description
    """
    print(argb)

Sphinx-build results of example

The directive produces the document tree which is essentially the same as which is produced by the following reST file:

.. Copyright (C) 2019, Nokia

Expected Command Line Interface
===============================

task_a
------

::

  Usage: program task_a [--options] [other tasks here ...]

  Docstring:
    Task a description.

    Args:
        arga:   arga description

  Options:
    -a STRING, --arga=STRING

task_b
------

::

  Usage: program task_b [--options] [other tasks here ...]

  Docstring:
    Task b description.

    Args:
        argb:   argb description

  Options:
    -a STRING, --argb=STRING

This is interpreted finally (without the title) to the following:

task_a

Usage: program task_a [--options] [other tasks here ...]

Docstring:
  Task a description.

  Args:
      arga:   arga description

Options:
  -a STRING, --arga=STRING

task_b

Usage: program task_b [--options] [other tasks here ...]

Docstring:
  Task b description.

  Args:
      argb:   argb description

Options:
  -a STRING, --argb=STRING