sphinxfortran.fortran_domain – Fortran domain

A fortran domain for sphinx

class sphinxfortran.fortran_domain.FortranCallField(name, names=(), label=None, rolename=None)[source]

Bases: sphinxfortran.fortran_domain.FortranField

is_grouped = True
make_field(types, domain, items, **kwargs)[source]
class sphinxfortran.fortran_domain.FortranCompleteField(name, names=(), typenames=(), label=None, rolename=None, typerolename=None, shapenames=None, attrnames=None, prefix=None, strong=True, can_collapse=False)[source]

Bases: sphinxfortran.fortran_domain.FortranField, sphinx.util.docfields.GroupedField

A doc field that is grouped and has type information for the arguments. It always has an argument. The argument can be linked using the given rolename, the type using the given typerolename.

Two uses are possible: either parameter and type description are given separately, using a field from names and one from typenames, respectively, or both are given using a field from names, see the example.

Example:

:param foo: description of parameter foo
:type foo:  SomeClass

-- or --

:param SomeClass foo: description of parameter foo
is_typed = 2
make_field(types, domain, items, shapes=None, attrs=None, modname=None, typename=None)[source]
sphinxfortran.fortran_domain.FortranCreateIndexEntry(indextext, fullname, modname)[source]
class sphinxfortran.fortran_domain.FortranCurrentModule(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: docutils.parsers.rst.Directive

This directive is just to tell Sphinx that we’re documenting stuff in module foo, but links to module foo won’t lead here.

final_argument_whitespace = False
has_content = False
option_spec = {}
optional_arguments = 1
required_arguments = 0
run()[source]
class sphinxfortran.fortran_domain.FortranDocFieldTransformer(directive, modname=None, typename=None)[source]

Bases: sphinx.util.docfields.DocFieldTransformer

Transforms field lists in “doc field” syntax into better-looking equivalents, using the field type definitions given on a domain.

preprocess_fieldtypes(types)[source]
scan_fieldarg(fieldname)[source]

Extract type, name, shape and attributes from a field name.

Some possible syntaxes:
 
  • p name
  • p type name(shape) [attr1,attr2]
  • p type name
  • p name [attr1, attr2]
Returns:

name, shape, type, list of attributes. if no shape is specified, it is set to None,

transform(node)[source]

Transform a single field list node.

class sphinxfortran.fortran_domain.FortranDomain(env)[source]

Bases: sphinx.domains.Domain

Fortran language domain.

clear_doc(docname)[source]

Remove traces of a document in the domain-specific inventories.

directives = {'autofunction': <class 'sphinxfortran.fortran_autodoc.FortranAutoFunctionDirective'>, 'automodule': <class 'sphinxfortran.fortran_autodoc.FortranAutoModuleDirective'>, 'autoprogram': <class 'sphinxfortran.fortran_autodoc.FortranAutoProgramDirective'>, 'autoroutine': <class 'sphinxfortran.fortran_autodoc.FortranAutoObjectDirective'>, 'autosrcfile': <class 'sphinxfortran.fortran_autodoc.FortranAutoSrcfileDirective'>, 'autosubroutine': <class 'sphinxfortran.fortran_autodoc.FortranAutoSubroutineDirective'>, 'currentmodule': <class 'sphinxfortran.fortran_domain.FortranCurrentModule'>, 'function': <class 'sphinxfortran.fortran_domain.FortranWithSig'>, 'module': <class 'sphinxfortran.fortran_domain.FortranModule'>, 'program': <class 'sphinxfortran.fortran_domain.FortranProgram'>, 'subroutine': <class 'sphinxfortran.fortran_domain.FortranWithSig'>, 'type': <class 'sphinxfortran.fortran_domain.FortranType'>, 'variable': <class 'sphinxfortran.fortran_domain.FortranObject'>}
find_obj(env, modname, name, role, searchorder=0)[source]

Find a Fortran object for “name”, perhaps using the given module and/or typename.

Params:
  • searchorder, optional: Start using relative search
get_objects()[source]

Return an iterable of “object descriptions”, which are tuples with five items:

  • name – fully qualified name
  • dispname – name to display when searching/linking
  • type – object type, a key in self.object_types
  • docname – the document where it is to be found
  • anchor – the anchor name for the object
  • priority – how “important” the object is (determines placement in search results)
    • 1: default priority (placed before full-text matches)
    • 0: object is important (placed before default-priority objects)
    • 2: object is unimportant (placed after full-text matches)
    • -1: object should not show up in search at all
indices = [<class 'sphinxfortran.fortran_domain.FortranModuleIndex'>]
initial_data = {'modules': {}, 'objects': {}}
label = 'Fortran'
name = 'f'
object_types = {'function': <sphinx.domains.ObjType object at 0x7f0497f33d10>, 'module': <sphinx.domains.ObjType object at 0x7f0497f33e50>, 'program': <sphinx.domains.ObjType object at 0x7f0497f33ad0>, 'subroutine': <sphinx.domains.ObjType object at 0x7f0497f33dd0>, 'type': <sphinx.domains.ObjType object at 0x7f0497f33b90>, 'variable': <sphinx.domains.ObjType object at 0x7f0497f33c50>}
resolve_xref(env, fromdocname, builder, type, target, node, contnode)[source]

Resolve the pending_xref node with the given typ and target.

This method should return a new node, to replace the xref node, containing the contnode which is the markup content of the cross-reference.

If no resolution can be found, None can be returned; the xref node will then given to the ‘missing-reference’ event, and if that yields no resolution, replaced by contnode.

The method can also raise sphinx.environment.NoUri to suppress the ‘missing-reference’ event being emitted.

roles = {'func': <sphinxfortran.fortran_domain.FortranXRefRole object at 0x7f0497f33f90>, 'mod': <sphinxfortran.fortran_domain.FortranXRefRole object at 0x7f0497f3c050>, 'prog': <sphinxfortran.fortran_domain.FortranXRefRole object at 0x7f0497f33ed0>, 'subr': <sphinxfortran.fortran_domain.FortranXRefRole object at 0x7f0497f33fd0>, 'type': <sphinxfortran.fortran_domain.FortranXRefRole object at 0x7f0497f33f10>, 'var': <sphinxfortran.fortran_domain.FortranXRefRole object at 0x7f0497f33f50>}
class sphinxfortran.fortran_domain.FortranField(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: docutils.parsers.rst.Directive

Directive to describe a change/addition/deprecation in a specific version.

final_argument_whitespace = True
has_content = True
option_spec = {'attrs': <function unchanged at 0x7f049bdca410>, 'shape': <function parse_shape at 0x7f0497f2a6e0>, 'type': <function unchanged at 0x7f049bdca410>}
optional_arguments = 0
required_arguments = 1
run()[source]
class sphinxfortran.fortran_domain.FortranModule(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: docutils.parsers.rst.Directive

Directive to mark description of a new module.

final_argument_whitespace = False
has_content = False
option_spec = {'deprecated': <function flag at 0x7f049bdca320>, 'noindex': <function flag at 0x7f049bdca320>, 'platform': <function <lambda> at 0x7f0497f39488>, 'synopsis': <function <lambda> at 0x7f0497f39500>}
optional_arguments = 0
required_arguments = 1
run()[source]
class sphinxfortran.fortran_domain.FortranModuleIndex(domain)[source]

Bases: sphinx.domains.Index

Index subclass to provide the Fortran module index.

generate(docnames=None)[source]

Return entries for the index given by name. If docnames is given, restrict to entries referring to these docnames.

The return value is a tuple of (content, collapse), where collapse is a boolean that determines if sub-entries should start collapsed (for output formats that support collapsing sub-entries).

content is a sequence of (letter, entries) tuples, where letter is the “heading” for the given entries, usually the starting letter.

entries is a sequence of single entries, where a single entry is a sequence [name, subtype, docname, anchor, extra, qualifier, descr]. The items in this sequence have the following meaning:

  • name – the name of the index entry to be displayed
  • subtype – sub-entry related type: 0 – normal entry 1 – entry with sub-entries 2 – sub-entry
  • docname – docname where the entry is located
  • anchor – anchor for the entry within docname
  • extra – extra info for the entry
  • qualifier – qualifier for the description
  • descr – description for the entry

Qualifier and description are not rendered e.g. in LaTeX output.

localname = iu'Fortran Module Index'
name = 'modindex'
shortname = iu'fortran modules'
class sphinxfortran.fortran_domain.FortranObject(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: sphinx.directives.ObjectDescription

Description of a general Fortran object.

_parens = ''
add_shape_and_attrs(signode, modname, ftype, shape, attrs)[source]
add_target_and_index(name, sig, signode)[source]

Add cross-reference IDs and entries to self.indexnode, if applicable.

name is whatever handle_signature() returned.

after_content()[source]

Called after parsing content. Used to reset information about the current directive context on the build environment.

before_content()[source]

Called before parsing content. Used to set information about the current directive context on the build environment.

doc_field_types = [<sphinxfortran.fortran_domain.FortranCompleteField object>, <sphinxfortran.fortran_domain.FortranCompleteField object>, <sphinxfortran.fortran_domain.FortranCompleteField object>, <sphinxfortran.fortran_domain.FortranCompleteField object>, <sphinxfortran.fortran_domain.FortranCallField object>, <sphinxfortran.fortran_domain.FortranCallField object>]
get_index_text(modname, name)[source]
get_signature_prefix(sig)[source]

May return a prefix to put before the object name in the signature.

handle_signature(sig, signode)[source]

Transform a Fortran signature into RST nodes. Returns (fully qualified name of the thing, classname if any).

If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present * it is added to the full name (return value) if not present

needs_arglist()[source]

May return true if an empty argument list is to be generated even if the document contains none.

option_spec = {'attrs': <function unchanged at 0x7f049bdca410>, 'module': <function unchanged at 0x7f049bdca410>, 'noindex': <function flag at 0x7f049bdca320>, 'shape': <function parse_shape at 0x7f0497f2a6e0>, 'type': <function unchanged at 0x7f049bdca410>}
stopwords = set(['integer', 'float', 'character', 'long', 'double'])
class sphinxfortran.fortran_domain.FortranProgram(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: sphinxfortran.fortran_domain.FortranSpecial, sphinxfortran.fortran_domain.WithFortranDocFieldTransformer, sphinxfortran.fortran_domain.FortranObject

class sphinxfortran.fortran_domain.FortranSpecial[source]
get_signature_prefix(sig)[source]

May return a prefix to put before the object name in the signature.

class sphinxfortran.fortran_domain.FortranType(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: sphinxfortran.fortran_domain.FortranSpecial, sphinxfortran.fortran_domain.WithFortranDocFieldTransformer, sphinxfortran.fortran_domain.FortranObject

before_content()[source]

Called before parsing content. Used to set information about the current directive context on the build environment.

class sphinxfortran.fortran_domain.FortranTypeField(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: sphinxfortran.fortran_domain.FortranObject

before_content()[source]

Called before parsing content. Used to set information about the current directive context on the build environment.

class sphinxfortran.fortran_domain.FortranWithSig(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Bases: sphinxfortran.fortran_domain.FortranSpecial, sphinxfortran.fortran_domain.WithFortranDocFieldTransformer, sphinxfortran.fortran_domain.FortranObject

Description of a function of subroutine

_parens = '()'
get_signature_prefix(sig)[source]

May return a prefix to put before the object name in the signature.

needs_arglist()[source]

May return true if an empty argument list is to be generated even if the document contains none.

class sphinxfortran.fortran_domain.FortranXRefRole(fix_parens=False, lowercase=False, nodeclass=None, innernodeclass=None, warn_dangling=False)[source]

Bases: sphinx.roles.XRefRole

Called after parsing title and target text, and creating the reference node (given in refnode). This method can alter the reference node and must return a new (or the same) (title, target) tuple.

class sphinxfortran.fortran_domain.WithFortranDocFieldTransformer[source]
run()[source]

Same as sphinx.directives.ObjectDescription() but using FortranDocFieldTransformer

sphinxfortran.fortran_domain._pseudo_parse_arglist(signode, arglist)[source]

“Parse” a list of arguments separated by commas.

Arguments can have “optional” annotations given by enclosing them in brackets. Currently, this will split at any comma, even if it’s inside a string literal (e.g. default argument value).

sphinxfortran.fortran_domain.add_shape(node, shape, modname=None, nodefmt=<class 'docutils.nodes.Text'>)[source]

Format a shape expression for a node

sphinxfortran.fortran_domain.convert_arithm(node, expr, modname=None, nodefmt=<class 'docutils.nodes.Text'>)[source]

Format an arithmetic expression for a node

sphinxfortran.fortran_domain.parse_shape(shape)[source]
sphinxfortran.fortran_domain.re_fieldname_match()

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

sphinxfortran.fortran_domain.setup(app)[source]