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

add_ribbon(app, pagename, templatename, …)	Adds “Edit me on GitHub” Ribbon to pages
as_extlink_filter(text)	Jinja2 filter converting identifier (list) to extlink format
generate_readme(recipe_basedir, output_dir, …)	Generates README.rst for the recipe in folder
generate_recipes(app)	Generates recipe RST files
prefixes_filter(text, split)	Jinja2 filter
resolve_required_by_xrefs(app, env, node, …)	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.
rst_escape_filter(text)	Jinja2 filter escaping RST symbols in text
rst_link_filter(text, url)	Jinja2 filter creating RST link
setup(app)	Set up sphinx extension
underline_filter(text)	Jinja2 filter adding =-underline to row of text

Classes

AutoRecipesDirective(name, arguments, …)	FIXME: This does not yet do ANYTHING!
CondaDomain(env)	Domain for Conda Packages
CondaObjectDescription(name, arguments, …)	Base class for ObjectDescription types in the CondaDomain
CondaPackage(name, arguments, options, …)	Directive ..conda:package:: describing a Package.
CondaRecipe(name, arguments, options, …)	Directive ..conda:recipe:: describing a Recipe.
LintDescriptionDirective(name, arguments, …)
PackageIndex(domain)	Index of Packages
Renderer(app, extra_context)	Jinja2 template renderer
RequiredByField(name[, names, label, …])	Field Type for directive ..conda:package:: for showing required-by.
RequirementsField(name[, names, label, …])	Field Type for ..conda:package:: for specifying dependencies.

Documentation

class bioconda_utils.sphinxext.AutoRecipesDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

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)

Domain for Conda Packages

clear_doc(docname)

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

get_objects()

Yields “object description” 5-tuples

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: search priority

• 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

merge_domaindata(docnames, otherdata)

Merge in data regarding docnames from a different domaindata inventory (coming from a subprocess in parallel builds).

Return type

None

resolve_any_xref(env, fromdocname, builder, target, node, contnode)

Resolve references from “any” role.

resolve_xref(env, fromdocname, builder, role, target, node, contnode)

Resolve the pending_xref node with the given role and target.

class bioconda_utils.sphinxext.CondaObjectDescription(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Base class for ObjectDescription types in the CondaDomain

add_target_and_index(name, sig, signodes)

Add to index and to domain data

Return type

None

before_content()

We register ourselves in the ref_context so that a later call to :depends:`packagename` knows within which package the dependency was added

get_index_text(name)

This yields the text with which the object is entered into the index.

Return type

str

handle_signature(sig, signode)

Transform signature into RST nodes

Return type

str

class bioconda_utils.sphinxext.CondaPackage(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Directive .. conda:package:: describing a Package

This directive takes two specialized field types, requirements and depends:

.. 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)

Directive .. conda:recipe:: describing a Recipe

class bioconda_utils.sphinxext.LintDescriptionDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

class bioconda_utils.sphinxext.PackageIndex(domain)

Index of Packages

generate(docnames=None)

build index

class bioconda_utils.sphinxext.Renderer(app, extra_context)

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)

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)

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)

Field Type for directive .. conda:package:: for showing required-by

This just creates the field name and field body with a pending_xref in the body that will later be filled with the reverse dependencies by resolve_required_by_xrefs

class bioconda_utils.sphinxext.RequirementsField(name, names=(), label=None, rolename=None, can_collapse=False)

Field Type for .. conda:package:: for specifying dependencies

This does two things different than GroupedField:

• No -- inserted between argument and value

• Entry 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)

Adds “Edit me on GitHub” Ribbon to pages

This hooks into html-page-context event and adds the parameters git_ribbon_url and git_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 the bioconda-utils repo

• recipes/*/README pages are assumed to be recipes and link to the meta.yaml

• all others are assumed to be RST docs and link to the docs/source/ folder in bioconda-utils

Todo

Fix hardcoding of values, should be a mapping that comes from conf.py.

bioconda_utils.sphinxext.as_extlink_filter(text)

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)

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)

Generates recipe RST files

• Checks out repository

• Prepares RepoData

• Selects recipes (if BIOCONDA_FILTER_RECIPES in environment)

• Dispatches calls to generate_readme for each recipe

• Removes old RST files

bioconda_utils.sphinxext.prefixes_filter(text, split)

Jinja2 filter

bioconda_utils.sphinxext.resolve_required_by_xrefs(app, env, node, contnode)

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 the RequiredByField fieldtype allowed in conda:package:: directives, where we replace the pending_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)

Jinja2 filter escaping RST symbols in text

>>> rst_excape_filter("running `cmd.sh`")
"running \`cmd.sh\`"

bioconda_utils.sphinxext.rst_link_filter(text, url)

Jinja2 filter creating RST link

>>> rst_link_filter("bla", "https://somewhere")
"`bla <https://somewhere>`_"

bioconda_utils.sphinxext.setup(app)

Set up sphinx extension

bioconda_utils.sphinxext.underline_filter(text)

Jinja2 filter adding =-underline to row of text

>>> underline_filter("headline")
"headline\n========"