sphinxext: Sphinx extensions

blocs

pyquickhelper.sphinxext.BlocRef (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A blocref entry, displayed in the form of an admonition. It takes the following options:

  • title: a title for the bloc

  • tag: a tag to have several categories of blocs

  • lid or label: a label to refer to

  • index: to add an entry to the index (comma separated)

Example:…

pyquickhelper.sphinxext.BlocRefList (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A list of all blocref entries, for a specific tag.

  • tag: a tag to filter bloc having this tag

  • sort: a way to sort the blocs based on the title, file, number, default: title

  • contents: add a bullet list with links to added blocs

Example:…

pyquickhelper.sphinxext.CmdRef (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A cmdref entry, displayed in the form of an admonition. It is used to reference a script a module is added as a command line. It takes the following options:

  • title: a title for the bloc

  • tag: a tag to have several categories of blocs, if not specified, it will be equal to cmd

  • lid or label: a label to refer to

  • index: to add an additional entry to the index (comma separated)

  • name: command line name, if populated, the directive displays the output of name --help.

  • path: used if the command line startswith -m

It works the same way as BlocRef. The command line can be something like -m <module> <command> .... The extension will call python in a separate process.

pyquickhelper.sphinxext.ExRef (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A exref entry, displayed in the form of an admonition. It takes the following options:

  • title: a title for the bloc

  • tag: a tag to have several categories of blocs (optional)

  • lid or label: a label to refer to

  • index: to add an entry to the index (comma separated)

Example:…

pyquickhelper.sphinxext.ExRefList (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A list of all exref entries, for a specific tag.

  • tag: a tag to filter bloc having this tag

  • sort: a way to sort the blocs based on the title, file, number, default: title

  • contents: add a bullet list with links to added blocs

Example:…

pyquickhelper.sphinxext.FaqRef (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A faqref entry, displayed in the form of an admonition. It takes the following options:

  • title: a title for the bloc

  • tag: a tag to have several categories of blocs (optional)

  • lid or label: a label to refer to

  • index: to add an entry to the index (comma separated)

Example:…

pyquickhelper.sphinxext.FaqRefList (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A list of all faqref entries, for a specific tag.

  • tag: a tag to filter bloc having this tag

  • sort: a way to sort the blocs based on the title, file, number, default: title

  • contents: add a bullet list with links to added blocs

Example:…

pyquickhelper.sphinxext.MathDef (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A mathdef entry, displayed in the form of an admonition. It takes the following options:

  • title: a title for the math

  • tag: a tag to have several categories of math

  • lid or label: a label to refer to

  • index: to add an entry to the index (comma separated)

Example:…

pyquickhelper.sphinxext.MathDefList (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A list of all mathdef entries, for a specific tag.

  • tag: a tag to have several categories of mathdef

  • contents: add a bullet list with links to added blocs

Example:…

pyquickhelper.sphinxext.NbRef (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A nbref entry, displayed in the form of an admonition. It takes the following options:

  • title: a title for the bloc

  • tag: a tag to have several categories of blocs, if not specified, it will be equal to nb

  • lid or label: a label to refer to

  • index: to add an additional entry to the index (comma separated)

See %encrypt_file for an example. All entries can be aggregated per tag with nbreflist:…

pyquickhelper.sphinxext.NbRefList (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A list of all nbref entries, for a specific tag.

  • tag: a tag to have several categories of nbref

  • contents: add a bullet list with links to added blocs

Example:…

pyquickhelper.sphinxext.TodoExt (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A todoext entry, displayed in the form of an admonition. It takes the following options:

  • title: a title for the todo (mandatory)

  • tag: a tag to have several categories of todo (mandatory)

  • issue: the issue requires extlinks to be defined and must contain key 'issue' (optional)

  • cost: a cost if the todo were to be fixed (optional)

  • priority: to prioritize items (optional)

  • hidden: if true, the todo does not appear where it is inserted but it will with a todolist (optional)

  • date: date (optional)

  • release: release number (optional)

Example:…

pyquickhelper.sphinxext.TodoExtList (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A list of all todoext entries, for a specific tag.

  • tag: a tag to have several categories of todoext

Example:…

blog

pyquickhelper.sphinxext.BlogPost (self, filename, encoding = ‘utf-8-sig’, raise_exception = False, extensions = None, conf = None, kwargs_overrides)

Defines a blog post.

build_tag (date, title)

Builds the tag for a post.

post_as_rst (self, language, directive = ‘blogpostagg’, cut = False)

Reproduces the text of the blog post, updates the image links.

pyquickhelper.sphinxext.BlogPostDirective (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Extracts information about a blog post described by a directive .. blogpost:: and modifies the documentation if env is not null. The directive handles the following options:

  • date: date of the blog (mandatory)

  • title: title (mandatory)

  • keywords: keywords, comma separated (mandatory)

  • categories: categories, comma separated (mandatory)

  • author: author (optional)

  • blog_background: can change the blog background (boolean, default is True)

  • lid or label: an id to refer to (optional)

pyquickhelper.sphinxext.BlogPostList (self, folder, encoding = ‘utf8’, language = ‘en’, extensions = None, conf = None, fLOG = <function noLOG at 0x7f5f8e8804c0>)

Defines a list of BlogPost.

category2url (cat)

Removes accents and spaces to get a clean url.

divide_list (ld, division)

Divides a list into buckets of division items.

get_categories (self)

Extracts the categories.

get_categories_group (self)

Extracts the categories with the posts associated to it.

get_files (self)

Extracts the files.

get_image (self, img)

Returns the local path to an image in this folder.

get_keywords (self)

Extracts the categories.

get_months (self)

Extracts the months.

get_months_group (self)

Extracts the months with the posts associated to it.

get_rst_links_down (self)

Builds the rst links to months or categories to displays the bottom of the aggregated pages.

get_rst_links_up (self)

Builds the rst links to months or categories to displays at the beginning of the aggregated pages.

produce_aggregated_post_page (name, lp, this, prev, next, main_page = ‘Blog’, rst_links_up = None, rst_links_down = None, index_terms = None, bold_title = None, language = ‘en’)

Writes the content of an aggregate page of blog posts.

write_aggregated (self, folder, division = 10, blog_title = ‘__BLOG_TITLE__’, blog_description = ‘__BLOG_DESCRIPTION__’, blog_root = ‘__BLOG_ROOT__’, only_html_index = True, only_html_agg = False)

Writes posts in a aggregated manner (post, categories, months).

write_aggregated_categories (self, folder, division = 10, rst_links_up = None, rst_links_down = None, only_html = True)

Writes posts in a aggregated manner per categories.

write_aggregated_chapters (self, folder)

Writes links to post per categories and per months.

write_aggregated_index (self, folder, hidden_files = None, hidden_files_html = None, only_html = True)

Writes an index.

write_aggregated_months (self, folder, division = 10, rst_links_up = None, rst_links_down = None, only_html = True)

Writes posts in a aggregated manner per months.

write_aggregated_post_list (folder, lp, division, prefix, encoding, rst_links_up = None, rst_links_down = None, index_terms = None, bold_title = None, language = ‘en’, only_html = True)

Writes list of posts in an aggregated manners.

write_aggregated_posts (self, folder, division = 10, rst_links_up = None, rst_links_down = None, only_html = True)

Writes posts in a aggregated manner.

pyquickhelper.sphinxext.BlogPostDirectiveAgg (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

same but for the same post in a aggregated pages

builder

pyquickhelper.sphinxext.sphinx_rst_builder.RstBuilder (self, args, kwargs)

Defines a RST builder.

code

pyquickhelper.sphinxext.setup_docassert (app)

Setup for docassert extension (sphinx). This changes DocFieldTransformer.transform and replaces it by a function which calls the current function and does extra checking on the list of parameters.

pyquickhelper.sphinxext.sphinx_autosignature.AutoSignatureDirective (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

This directive displays a shorter signature than sphinx.ext.autodoc. Available options:

  • nosummary: do not display a summary (shorten)

  • annotation: shows annotation

  • nolink: if False, add a link to a full documentation (produced by sphinx.ext.autodoc)

  • members: shows members of a class

  • path: three options, full displays the full path including submodules, name displays the last name, import displays the shortest syntax to import it (default).

  • debug: diplays debug information

  • syspath: additional paths to add to sys.path before importing, ‘;’ separated list

The signature is not always available for builtin functions or C++ functions depending on the way to bind them to Python. See Set the __text_signature__ attribute of callables.

The signature may not be infered by module inspect if the function is a compiled C function. In that case, the signature must be added to the documentation. It will parsed by autosignature with by function enumerate_extract_signature with regular expressions.

execution

pyquickhelper.sphinxext.RunPythonDirective (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Extracts script to run described by .. runpython:: and modifies the documentation.

style, content

pyquickhelper.sphinxext.process_downloadlink_role (role, rawtext, text, lineno, inliner, options = None, content = None)

Defines custom role downloadlink. The following instructions defines a link which can be displayed or hidden based on the output format. The following directive creates a link to page.html only for the HTML output, it also copies the files next to the source and not in the folder _downloads. The link does not push the user to download the file but to see it.

pyquickhelper.sphinxext.bigger_role (role, rawtext, text, lineno, inliner, options = None, content = None)

Defines custom role bigger. The following instructions defines buttons of size 20 (text)…

pyquickhelper.sphinxext.sphinx_collapse_extension.CollapseDirective (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

A collapse adds hide/unhide button for a part of HTML page. It has no effect in other formats.

  • legend: legend for the button, if not precise, it will be hide / unhide. Example: :legend: hide/unhide.

  • hide: the text is shown by default unless this option is set up.

Example:…

pyquickhelper.sphinxext.sphinx_epkg_extension.epkg_role (role, rawtext, text, lineno, inliner, options = None, content = None)

Defines custom role epkg. A list of supported urls must be defined in the configuration file. It wants to replace something like…

pyquickhelper.sphinxext.githublink_role (role, rawtext, text, lineno, inliner, options = None, content = None)

Defines custom role githublink. The following instruction add a link to the documentation on github.

pyquickhelper.sphinxext.PostContentsDirective (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Defines a sphinx extension which proposes a new version of .. contents:: which takes into account titles dynamically added.

Example:…

pyquickhelper.sphinxext.ShareNetDirective (self, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Adds buttons to share a page. It can be done by adding:…

pyquickhelper.sphinxext.sphinx_template_extension.tpl_role (role, rawtext, text, lineno, inliner, options = None, content = None)

Defines custom role tpl. A template must be specified in the configuration file.

pyquickhelper.sphinxext.python_link_doc (m, o = None, format = ‘rst’)

Returns a url about Python documentation.