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

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, …)

RecipeIndex(domain)

Index of Recipes

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

clear_doc(docname)[source]

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

get_objects()[source]

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)[source]

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)[source]

Resolve references from “any” role.

resolve_xref(env, fromdocname, builder, role, target, node, contnode)[source]

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)[source]

Bases: sphinx.directives.ObjectDescription

Base class for ObjectDescription types in the CondaDomain

add_target_and_index(name, sig, signodes)[source]

Add to index and to domain data

Return type

None

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

get_index_text(name)[source]

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

Return type

str

handle_signature(sig, signode)[source]

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)[source]

Bases: bioconda_utils.sphinxext.CondaObjectDescription

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)[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]

Bases: sphinx.util.docutils.SphinxDirective

class bioconda_utils.sphinxext.RecipeIndex(domain)[source]

Bases: sphinx.domains.Index

Index of Recipes

generate(docnames=None)[source]

build index

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-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)[source]

Bases: sphinx.util.docfields.GroupedField

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)[source]

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.

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

bioconda_utils.sphinxext.prefixes_filter(text, split)[source]

Jinja2 filter

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 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)[source]

Jinja2 filter escaping RST symbols in text

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

Jinja2 filter creating RST link

>>> rst_link_filter("bla", "https://somewhere")
"`bla <https://somewhere>`_"
bioconda_utils.sphinxext.setup(app)[source]

Set up sphinx extension

bioconda_utils.sphinxext.underline_filter(text)[source]

Jinja2 filter adding =-underline to row of text

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