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')[source]¶ 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_index
()[source]¶ Register modules, functions, types and module variables for quick access
Index constituents are:
-
filter_by_srcfile
(sfile, mode=None, objtype=None, **kwargs)[source]¶ 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)[source]¶ Filter and format the attributes (optional, in/out/inout, etc) of a variable
Parameters: - block: a variable block
-
format_argdim
(block)[source]¶ Format the dimension of a variable
Parameters: - block: a variable block
-
format_argfield
(blockvar, role=None, block=None)[source]¶ Format the description of a variable
Parameters: - block: a variable block
-
format_declaration
(dectype, name, description=None, indent=0, bullet=None, options=None)[source]¶ Create an simple rst declaration
Example: >>> print format_declaration('var', 'myvar', 'my description', indent=1, bullet='-') - .. f:var:: myvar
my description
-
format_funcref
(fname, current_module=None, aliasof=None, module=None)[source]¶ 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)[source]¶ Convert a list of lines to text
-
format_quickaccess
(module, indent=<function indent>)[source]¶ Format an abstract of all types, variables and routines of a module
-
format_routine
(block, indent=0)[source]¶ Format the description of a function, a subroutine or a program
-
format_rubric
(text, indent=0)[source]¶ Create a simple rst rubric with indentation
Parameters: - text: text of the rubric
Example: >>> print o.format_rubric('My title', '-') .. rubric:: My rubric
-
format_srcfile
(srcfile, indent=0, objtype=None, search_mode='basename', **kwargs)[source]¶ 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)[source]¶ Format a subsection for describing list of subroutines, types, etc
-
format_title
(text, ulc=None, indent=0)[source]¶ 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)[source]¶ Format the description of a module type
Parameters: - block: block of the type
-
format_use
(block, indent=0, short=False)[source]¶ Format use statement
Parameters: - block: a module block
-
format_var
(block, indent=0, bullet=True)[source]¶ Format the description of a module type
Parameters: - block: block of the variable
-
format_variables
(block, indent=0)[source]¶ Format the description of all variables (global or module)
-
get_blocksrc
(block, src=None, istart=0, getidx=False, stopmatch=None, exclude=None)[source]¶ 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)[source]¶ Search for and return the comment starting after
iline
insrc
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
: ifgetilast is True
-
get_synopsis
(block, nmax=2)[source]¶ 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.
-
ic
¶ Indentation character
-
sst
¶ Subsection type (“title” or “rubric”)
-
strip_blocksrc
(block, exc, src=None)[source]¶ 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
[source]¶ Bases:
exceptions.Exception
-
class
sphinxfortran.fortran_autodoc.
FortranAutoFunctionDirective
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ 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)[source]¶ Bases:
docutils.parsers.rst.Directive
-
has_content
= True¶
-
option_spec
= {'title_underline': <function unchanged at 0x7f64ded1f578>, 'indent': <function fmt_indent at 0x7f64d945f668>, 'subsection_type': <function unchanged at 0x7f64ded1f578>}¶
-
optional_arguments
= 0¶
-
required_arguments
= 1¶
-
-
class
sphinxfortran.fortran_autodoc.
FortranAutoObjectDirective
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ 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 attributetotos
containg index of all related fortran objects, and methodformat_totos()
for formatting the object.
-
_objtype
= 'routine'
-
_warning
= 'Wrong routine name: %s'
-
has_content
= False¶
-
option_spec
= {}¶
-
optional_arguments
= 0¶
-
required_arguments
= 1¶
-
-
class
sphinxfortran.fortran_autodoc.
FortranAutoProgramDirective
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ Bases:
docutils.parsers.rst.Directive
-
has_content
= False¶
-
option_spec
= {}¶
-
optional_arguments
= 0¶
-
required_arguments
= 1¶
-
-
class
sphinxfortran.fortran_autodoc.
FortranAutoSrcfileDirective
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ Bases:
docutils.parsers.rst.Directive
-
has_content
= False¶
-
option_spec
= {'objtype': <function unchanged at 0x7f64ded1f578>, 'search_mode': <function unchanged at 0x7f64ded1f578>}¶
-
optional_arguments
= 0¶
-
required_arguments
= 1¶
-
-
class
sphinxfortran.fortran_autodoc.
FortranAutoSubroutineDirective
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ 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)[source]¶ 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)[source]¶ Bases:
sphinxfortran.fortran_autodoc.FortranAutoObjectDirective
-
_objtype
= 'variable'¶
-
_warning
= 'Wrong variable name: %s'¶
-