capsul.sphinxext module

Extension to sphinx to document Capsul processes

This moduls allows to make sphinx source to automatically document Capsul processes and pipelines. The module can be used as a commandline:

python -m capsul.sphinxext.capsul_pipeline_rst -i morphologist.capsul -o processes_docs --schema

It can be automatically run when building sphinx docs (inside the sphinx-build process) by adding at the end of the conf.py file in sphinx sources:

# generate pipeline and processes docs
# we must actually write in sources for now.
import subprocess

module_to_document = 'morphologist.capsul'  # replace with your modules set
sphinx_dir = os.path.dirname(__file__)
proc_rst_dir = os.path.join(sphinx_dir, 'process_docs')
if not os.path.exists(proc_rst_dir):
    os.makedirs(proc_rst_dir)
cmd = [sys.executable, '-m', 'capsul.sphinxext.capsul_pipeline_rst',
      '-i', module_to_document, '-o', proc_rst_dir, '--schema']
print('generating CAPSUL processes docs...')
print(cmd)
subprocess.check_output(cmd)

The documentation will include all pipelines and processes in the module to be documented (including Nipype interfaces), and will be built from the processes documentation: docstrings, and parameters descriptions (desc property of processes traits), as in the processes get_help() method. An index.rst file will be created for each sub-module of the main one, and contain links to pipelines and processes docs there.

Then within the sphinx docs sources (index.rst for instance, or any other sphinx source file), you can include them:

# interestingly, sphinx lexers do not support sphinx language ;)

.. toctree::

    process_docs/morphologist/capsul/index.rst

class capsul.sphinxext.layoutdocgen.LayoutHelperWriter(module_names, root_module_name, rst_extension='.rst')

A basic class to create sphinx layout and associated index.

Initialize the LayoutHelperWriter class

Parameters:

• module_names (list of str (mandatory)) – list of modules defined in the project
• root_module_name (str (mandatory)) – the name of the python package
• rst_extension (string (optional)) – Extension for reST files, default ‘.rst’

generate_index_entry(module_name, indent=4)

Make autodoc documentation of pilots

Parameters:

• module_name (string) – the name of the module we want to index
• ident (int) – the number of blank prefix

Returns:

ad – the reST formated index description.

Return type:

string

rst2html(rst)

Convert a rst formated string to an html string.

Parameters:rst (str (mandatory)) – the rst formated string. Returns:out – the html formated string. Return type:str

title_for(title)

Create a title from a underscore-separated string.

Parameters:title (str (mandatory)) – the string to format. Returns:out – the formated string. Return type:str

write_index(outdir, froot='index', rst_extension='.rst')

Make a reST API index file from python modules

Parameters:

• outdir (string (mandatory)) – Directory to which to write generated index file
• froot (string (optional)) – root (filename without extension) of filename to write to Defaults to ‘index’. We add rst_extension.
• rst_extension (string (optional)) – Extension for reST files, default ‘.rst’

write_installation(outdir)

Generate the installation recommendations.

Parameters:outdir (string) – Directory name in which to store files

write_layout(outdir)

Generate the sphinx layout.

Parameters:outdir (string) – Directory name in which to store files

capsul.sphinxext.load_pilots.load_pilots(root, path, root_module_name)

Load all the pilot functions.

Path is recursively scanned for __init__.py files. Any function declared inside whose name start with pilot_ will be loaded.

Parameters:

• root (str (mandatory)) – path to the use_cases module.
• path (str) – path to the module.
• root_module_name (str (mandatory)) – the name of the package.

Returns:

pilots – a dict with module name as keys referencing to function module used for unitest.

Return type:

dict

class capsul.sphinxext.pipelinedocgen.PipelineHelpWriter(pipelines, rst_extension='.rst', short_names={})

Class for automatic generation of pipeline API documentations in Sphinx-parsable reST format.

Initialize package for parsing

Parameters:

• pipelines (list (mandatory)) – list of pipeline class
• rst_extension (string (optional)) – extension for reST files, default ‘.rst’
• short_names (dict (optional)) – translation dict for module/pipeline file names

generate_api_doc(pipeline, schema)

Make autodoc documentation for a pipeline python module

Parameters:

• pipeline (string) – python location of pipeline - e.g ‘caps.fmri.PIPELINE’
• schema (string) – path to the pipeline representation image

Returns:

• ad (string) – contents of API doc
• title (string) – the fist line of the docstring

get_short_name(name)

Get a short file name prefix for module/process in the short_names dict. Used to build “reasonably short” path/file names.

write_api_docs(outdir=None, returnrst=False)

Generate API reST files.

Parameters:

• outdir (string (optional, default None)) – directory name in which to store files. Automatic filenames are created for each module.
• returnrst (bool (optional, default False)) – if True return the rst string documentation, otherwise write it to disk.

Notes

Sets self.written_modules to list of written modules

write_index(outdir, froot='index', relative_to=None, rst_extension='.rst')

Make a reST API index file from the list of written files

Parameters:

• outdir (string (mandatory)) – directory to which to write generated index file
• froot (string (optional)) – root (filename without extension) of filename to write to Defaults to ‘index’. We add rst_extension.
• relative_to (string) – path to which written filenames are relative. This component of the written file path will be removed from outdir, in the generated index. Default is None, meaning, leave path as it is.
• rst_extension (string (optional)) – extension for reST files, default ‘.rst’

write_main_index(outdir, module_name, root_module_name, froot='index', rst_extension='.rst', have_usecases=True)

Make a reST API index file for the module

Parameters:

• outdir (string (mandatory)) – Directory to which to write generated index file
• module_name (str (mandatory)) – The name of module from which we want to generate an index.
• root_module_name (str (mandatory)) – The python package name
• froot (string (optional)) – root (filename without extension) of filename to write to Defaults to ‘index’. We add rst_extension.
• rst_extension (string (optional)) – Extension for reST files, default ‘.rst’

class capsul.sphinxext.usecasesdocgen.UseCasesHelperWriter(pilots, rst_extension='.rst')

A basic class to convert the pilot codes to rst use cases

Initialize the UseCasesHelper class

Parameters:

• pilots (list of @function (mandatory)) – list of pilot functions.
• rst_extension (string (optional)) – Extension for reST files, default ‘.rst’.

generate_usecases_doc(src_code, module_name)

Make autodoc documentation of pilots

Parameters:src_code (string) – pilot source code. Returns:ad – the use case reST formated documentation. Return type:string

getsource(function)

Method that returns the source code of a function

Parameters:function (@function (mandatory)) – a python function. Returns:srccode – the function source code. Return type:str

write_index(outdir, froot='index', relative_to=None, rst_extension='.rst')

Make a reST API index file from written files

Parameters:

• outdir (string (mandatory)) – Directory to which to write generated index file
• froot (string (optional)) – root (filename without extension) of filename to write to Defaults to ‘index’. We add rst_extension.
• relative_to (string) – path to which written filenames are relative. This component of the written file path will be removed from outdir, in the generated index. Default is None, meaning, leave path as it is.
• rst_extension (string (optional)) – Extension for reST files, default ‘.rst’

write_usecases_docs(outdir=None, returnrst=False)

Generate Use Cases reST files.

Parameters:

• outdir (string) – Directory name in which to store files. We create automatic filenames for each Use case.
• returnrst (bool (optional, default False)) – if True return the rst string documentation, otherwise write it to disk.

Commands

• capsul_pipeline_rst.py
• capsul_pipeline_view.py
• capsul_sphinx_layout.py
• capsul_usecases_rst.py