sphinxfortran.fortran_autodoc – Fortran auto-documenter

Sphinx extension for autodocumenting fortran codes.

class sphinxfortran.fortran_autodoc.F90toRst(ffiles, ic='t', ulc='-', vl=0, encoding='utf8', sst='rubric')

Bases: object

Fortran 90 parser and restructeredtext formatter

Parameters:

• ffiles: Fortran files (glob expression allowed) or dir (or list of)

Options:

• ic: Indentation char.
• ulc: Underline char for titles.
• sst: Subsection type.
• vl: Verbose level (0=quiet).

_fmt_fvardesc = '%(vtype)s%(vdim)s %(vattr)s%(vdesc)s'

_fmt_vardesc = ':%(role)s %(vtype)s %(vname)s%(vdim)s%(vattr)s: %(vdesc)s'

_fmt_vattr = ' [%(vattr)s]'

_re_comment_match()

match(string[, pos[, endpos]]) –> match object or None. Matches zero or more characters at the beginning of the string

_re_space_prefix_match()

match(string[, pos[, endpos]]) –> match object or None. Matches zero or more characters at the beginning of the string

_re_unended_match()

match(string[, pos[, endpos]]) –> match object or None. Matches zero or more characters at the beginning of the string

_re_unstarted_match()

match(string[, pos[, endpos]]) –> match object or None. Matches zero or more characters at the beginning of the string

build_callfrom_index()

For each function, index which function call it

build_index()

Register modules, functions, types and module variables for quick access

Index constituents are:

modules

Dictionary where each key is a module name, and each value is the cracked block.

routines

Module specific functions and subroutines

types

Module specific types

variables

Module specific variables

filter_by_srcfile(sfile, mode=None, objtype=None, **kwargs)

Search for subblocks according to origin file

Params:

• sfile: Source file name.
• mode, optional: Mode for searching for sfile. If "strict", exact match is needed, else only basename.
• objtype, optional: Restrict search to one or a list of object types (i.e. "function", "program", etc).

format_argattr(block)

Filter and format the attributes (optional, in/out/inout, etc) of a variable

Parameters:

• block: a variable block

format_argdim(block)

Format the dimension of a variable

Parameters:

• block: a variable block

format_argfield(blockvar, role=None, block=None)

Format the description of a variable

Parameters:

• block: a variable block

format_argtype(block)

format_declaration(dectype, name, description=None, indent=0, bullet=None, options=None)

Create an simple rst declaration

Example:

>>> print format_declaration('var', 'myvar', 'my description', indent=1, bullet='-')
    - .. f:var:: myvar

my description

format_description(block, indent=0)

Format the description of an object

format_funcref(fname, current_module=None, aliasof=None, module=None)

Format the reference link to a module function

Formatting may vary depending on if function is local and is an alias.

Example:

>>> print obj.format_type('myfunc')
:f:func:`~mymodule.myfunc`

format_function(block, indent=0)

Format the description of a function, a subroutine or a program

format_lines(lines, indent=0, bullet=None, nlc='\n', strip=False)

Convert a list of lines to text

format_module(block, indent=0)

Recursively format a module and its declarations

format_options(options, indent=0)

Format directive options

format_quickaccess(module, indent=<function indent>)

Format an abstract of all types, variables and routines of a module

format_routine(block, indent=0)

Format the description of a function, a subroutine or a program

format_routines(block, indent=0)

Format the list of all subroutines and functions

format_rubric(text, indent=0)

Create a simple rst rubric with indentation

Parameters:

• text: text of the rubric

Example:

>>> print o.format_rubric('My title', '-')
.. rubric:: My rubric

format_signature(block)

format_srcfile(srcfile, indent=0, objtype=None, search_mode='basename', **kwargs)

Format all declaration of a file, except modules

format_subroutine(block, indent=0)

Format the description of a function, a subroutine or a program

format_subsection(text, indent=<function indent>, **kwargs)

Format a subsection for describing list of subroutines, types, etc

format_title(text, ulc=None, indent=0)

Create a simple rst titlec with indentation

Parameters:

• text: text of the title

Options:

• ulc: underline character (default to attribute ucl)

Example:

>>> print o.format_title('My title', '-')
My title
--------

format_type(block, indent=0, bullet=True)

Format the description of a module type

Parameters:

• block: block of the type

format_types(block, indent=0)

Format the description of all fortran types

format_use(block, indent=0, short=False)

Format use statement

Parameters:

• block: a module block

format_var(block, indent=0, bullet=True)

Format the description of a module type

Parameters:

• block: block of the variable

format_variables(block, indent=0)

Format the description of all variables (global or module)

get_blocklist(choice, module)

Get the list of types, variables or function of a module

get_blocksrc(block, src=None, istart=0, getidx=False, stopmatch=None, exclude=None)

Extract an identified block of source code

Parameters:

• block: Cracked block

Options:

• src: List of source line including the block
• istart: Start searching from this line number

Return:

None or a list of lines

get_comment(src, iline=1, aslist=False, stripped=False, getilast=False, rightafter=True)

Search for and return the comment starting after iline in src

Params:

• src: A list of lines.
• iline, optional: Index of first line to read.
• aslist, optional: Return the comment as a list.
• stripped, optional: Strip each line of comment.
• getilast, optional: Get also index of last line of comment.
• rightafter, optional: Suppose the comment right after the signature line. If True, it prevents from reading a comment that is not a description of the routine.

Return:

• scomment: string or list
• OR scomment,ilast: if getilast is True

get_ic()

Get the indentation character

get_module(block)

Get the name of the current module

get_src(block)

Get the source lines of the file including this block

get_sst()

Get the subsection type

get_synopsis(block, nmax=2)

Get the first nmax non empty lines of the function, type or module comment as 1 line.

If the header has more than nmax lines, the first one is taken and appended of ‘...’. If description if empty, it returns an empty string.

get_ulc()

Get the underline character for title inside module description

get_varopts(block)

Get options for variable declaration as a dict

ic

Indentation character

indent(n)

Get a proper indentation

join_src(src)

Join unended lines that does not finish with a comment

scan()

Scan

scan_container(block, insrc=None)

Scan a block of program, routines or type

set_ic(ic)

Set the indentation character

set_sst(sst)

Set the subsection type

set_ulc(ulc)

Set the underline character for title inside module description

sst

Subsection type (“title” or “rubric”)

strip_blocksrc(block, exc, src=None)

Strip blocks from source lines

Parameters:

• block:
• exc list of block type to remove

Options:

• src: list of source lines

Example:

>>> obj.strip_blocksrc(lines, 'type')
>>> obj.strip_blocksrc(lines, ['function', 'type']

ulc

Underline character for title inside module description

exception sphinxfortran.fortran_autodoc.F90toRstException

Bases: exceptions.Exception

class sphinxfortran.fortran_autodoc.FortranAutoFunctionDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinxfortran.fortran_autodoc.FortranAutoObjectDirective

_objtype = 'function'

_warning = 'Wrong function name: %s'

class sphinxfortran.fortran_autodoc.FortranAutoModuleDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: docutils.parsers.rst.Directive

has_content = True

option_spec = {'title_underline': <function unchanged at 0x7f481d5e15f0>, 'indent': <function fmt_indent at 0x7f4817acc668>, 'subsection_type': <function unchanged at 0x7f481d5e15f0>}

optional_arguments = 0

required_arguments = 1

run()

class sphinxfortran.fortran_autodoc.FortranAutoObjectDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: docutils.parsers.rst.Directive

Generic directive for fortran object auto-documentation

Redefine _warning and _objtype attribute when subcassling.

_warning

Warning message when object is not found, like:

>>> _warning = 'Wrong function or subroutine name: %s'

_objtype

Type of fortran object. If “toto” is set as object type, then F90toRst must have attribute totos containg index of all related fortran objects, and method format_totos() for formatting the object.

_objtype = 'routine'

_warning = 'Wrong routine name: %s'

has_content = False

option_spec = {}

optional_arguments = 0

required_arguments = 1

run()

class sphinxfortran.fortran_autodoc.FortranAutoProgramDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: docutils.parsers.rst.Directive

has_content = False

option_spec = {}

optional_arguments = 0

required_arguments = 1

run()

class sphinxfortran.fortran_autodoc.FortranAutoSrcfileDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: docutils.parsers.rst.Directive

has_content = False

option_spec = {'objtype': <function unchanged at 0x7f481d5e15f0>, 'search_mode': <function unchanged at 0x7f481d5e15f0>}

optional_arguments = 0

required_arguments = 1

run()

class sphinxfortran.fortran_autodoc.FortranAutoSubroutineDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinxfortran.fortran_autodoc.FortranAutoObjectDirective

_objtype = 'subroutine'

_warning = 'Wrong subroutine name: %s'

class sphinxfortran.fortran_autodoc.FortranAutoTypeDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinxfortran.fortran_autodoc.FortranAutoObjectDirective

_objtype = 'type'

_warning = 'Wrong type name: %s'

class sphinxfortran.fortran_autodoc.FortranAutoVariableDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: sphinxfortran.fortran_autodoc.FortranAutoObjectDirective

_objtype = 'variable'

_warning = 'Wrong variable name: %s'

sphinxfortran.fortran_autodoc.fmt_indent(string)

sphinxfortran.fortran_autodoc.fortran_parse(app)

sphinxfortran.fortran_autodoc.list_files(fortran_src, exts=['f', 'f90', 'f95'], absolute=True)

Get the list of fortran files

sphinxfortran.fortran_autodoc.setup(app)