sphinxext¶
Bioconda-Utils sphinx extension
This module builds the documentation for our recipes
To build the documentation locally, use e.g:
make -C docs/ BIOCONDA_FILTER_RECIPES=10 SPHINXOPTS="-E" html
Environment Variables
-
BIOCONDA_FILTER_RECIPES
¶ Use this environment variable to reduce the number of recipes for which documentation pages are built. If set to an integer (including 0), the first n recipes are included. Otherwise, the contents are considered a regular expression recipes must match to be included.
Functions
|
Adds “Edit me on GitHub” Ribbon to pages |
|
Jinja2 filter converting identifier (list) to extlink format |
|
Generates README.rst for the recipe in folder |
|
Generates recipe RST files |
|
Jinja2 filter |
|
Now that all recipes and packages have been parsed, we are called here for each |
|
Jinja2 filter escaping RST symbols in text |
|
Jinja2 filter creating RST link |
|
Set up sphinx extension |
|
Jinja2 filter adding =-underline to row of text |
Classes
|
FIXME: This does not yet do ANYTHING! |
|
Domain for Conda Packages |
|
Base class for |
|
Directive |
|
Directive |
|
|
|
Index of Recipes |
|
Jinja2 template renderer |
|
Field Type for directive |
|
Field Type for |
Documentation
-
class
bioconda_utils.sphinxext.
AutoRecipesDirective
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ Bases:
docutils.parsers.rst.Directive
FIXME: This does not yet do ANYTHING!
In theory, a directive like this should act as a hook for a repo to generate stubs for, similar to other autoXYZ directives.
-
class
bioconda_utils.sphinxext.
CondaDomain
(env)[source]¶ Bases:
sphinx.domains.Domain
Domain for Conda Packages
-
get_objects
()[source]¶ Yields “object description” 5-tuples
name
: fully qualified namedispname
: name to display when searching/linkingtype
: object type, a key inself.object_types
docname
: the document where it is to be foundanchor
: the anchor name for the objectpriority
: search priority1: 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
-
merge_domaindata
(docnames, otherdata)[source]¶ Merge in data regarding docnames from a different domaindata inventory (coming from a subprocess in parallel builds).
- Return type
None
-
-
class
bioconda_utils.sphinxext.
CondaObjectDescription
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ Bases:
sphinx.directives.ObjectDescription
Base class for
ObjectDescription
types in theCondaDomain
-
before_content
()[source]¶ We register ourselves in the
ref_context
so that a later call to:depends:`packagename`
knows within which package the dependency was added
-
-
class
bioconda_utils.sphinxext.
CondaPackage
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ Bases:
bioconda_utils.sphinxext.CondaObjectDescription
Directive
.. conda:package::
describing a PackageThis directive takes two specialized field types,
requirements
anddepends
:.. conda:package:: mypkg1 :depends mypkg2: 2.0 :depends mypkg3: :requirements:
:depends pkgname: [version]
Adds a dependency to the package.
:requirements:
Lists packages which referenced this package via
:depends pkgname:
-
class
bioconda_utils.sphinxext.
CondaRecipe
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶ Bases:
bioconda_utils.sphinxext.CondaObjectDescription
Directive
.. conda:recipe::
describing a Recipe
-
class
bioconda_utils.sphinxext.
LintDescriptionDirective
(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶
-
class
bioconda_utils.sphinxext.
RecipeIndex
(domain)[source]¶ Bases:
sphinx.domains.Index
Index of Recipes
-
class
bioconda_utils.sphinxext.
Renderer
(app, extra_context)[source]¶ Bases:
object
Jinja2 template renderer
Loads and caches templates from paths configured in conf.py
Makes additional jinja filters available: - underline – turn text into a RSt level 1 headline - escape – escape RST special characters - as_extlink – convert (list of) identifiers to extlink references
-
render
(template_name, context)[source]¶ Render a template file to string
- Parameters
template_name – Name of template file
context – dictionary to pass to jinja
-
render_to_file
(file_name, template_name, context)[source]¶ Render a template file to a file
Ensures that target directories exist and only writes the file if the content has changed.
- Parameters
file_name – Target file name
template_name – Name of template file
context – dictionary to pass to jinja
- Returns
True if a file was written
-
class
bioconda_utils.sphinxext.
RequiredByField
(name, names=(), label=None, has_arg=True, rolename=None, bodyrolename=None)[source]¶ Bases:
sphinx.util.docfields.Field
Field Type for directive
.. conda:package::
for showing required-byThis just creates the field name and field body with a
pending_xref
in the body that will later be filled with the reverse dependencies byresolve_required_by_xrefs
-
class
bioconda_utils.sphinxext.
RequirementsField
(name, names=(), label=None, rolename=None, can_collapse=False)[source]¶ Bases:
sphinx.util.docfields.GroupedField
Field Type for
.. conda:package::
for specifying dependenciesThis does two things different than
GroupedField
:No
--
inserted between argument and valueEntry added to domain data
backrefs
so that we can use the requirements to collect required-by data later.
-
bioconda_utils.sphinxext.
add_ribbon
(app, pagename, templatename, context, doctree)[source]¶ Adds “Edit me on GitHub” Ribbon to pages
This hooks into
html-page-context
event and adds the parametersgit_ribbon_url
andgit_ribbon_message
to the context from which the HTML templates (layout.html
) are expanded.It understands three types of pages:
_autosummary
and_modules
prefixed pages are assumed to be code and link to thebioconda-utils
reporecipes/*/README
pages are assumed to be recipes and link to themeta.yaml
all others are assumed to be RST docs and link to the
docs/source/
folder inbioconda-utils
Todo
Fix hardcoding of values, should be a mapping that comes from
conf.py
.
-
bioconda_utils.sphinxext.
as_extlink_filter
(text)[source]¶ Jinja2 filter converting identifier (list) to extlink format
- Parameters
text – may be string or list of strings
>>> as_extlink_filter("biotools:abyss") "biotools: :biotool:`abyss`"
>>> as_extlink_filter(["biotools:abyss", "doi:123"]) "biotools: :biotool:`abyss`, doi: :doi:`123`"
-
bioconda_utils.sphinxext.
generate_readme
(recipe_basedir, output_dir, folder, repodata, renderer)[source]¶ Generates README.rst for the recipe in folder
- Parameters
folder – Toplevel folder name in recipes directory
repodata – RepoData object
renderer – Renderer object
- Returns
List of template_options for each concurrent version for which meta.yaml files exist in the recipe folder and its subfolders
-
bioconda_utils.sphinxext.
generate_recipes
(app)[source]¶ Generates recipe RST files
Checks out repository
Prepares
RepoData
Selects recipes (if
BIOCONDA_FILTER_RECIPES
in environment)Dispatches calls to
generate_readme
for each recipeRemoves old RST files
-
bioconda_utils.sphinxext.
resolve_required_by_xrefs
(app, env, node, contnode)[source]¶ Now that all recipes and packages have been parsed, we are called here for each
pending_xref
node that sphinx has not been able to resolve.We handle specifically the
requiredby
reftype created by theRequiredByField
fieldtype allowed inconda:package::
directives, where we replace thepending_ref
node with a bullet list of reference nodes pointing to the package pages that “depended” on the package.
-
bioconda_utils.sphinxext.
rst_escape_filter
(text)[source]¶ Jinja2 filter escaping RST symbols in text
>>> rst_excape_filter("running `cmd.sh`") "running \`cmd.sh\`"