gp-libs · Python Package License Code Coverage#

Incubating / dogfooding some sphinx extensions and pytest plugins on git-pull projects, e.g. cihai, vcs-python, or tmux-python.

doctest for reStructured and markdown#

Two components:

  1. doctest_docutils module: Same specification as doctest, but can parse reStructuredText and markdown

  2. pytest_doctest_docutils: Pytest plugin, collects test items for pytest for reStructuredText and markdown files

    This means you can do:

    $ pytest docs

doctest module#

This extends standard library doctest to support anything docutils can parse. It can parse reStructuredText (.rst) and markdown (.md).

See more: https://gp-libs.git-pull.com/doctest/

Supported styles#

It supports two barebones directives:

  • docutils’ doctest_block

    >>> 2 + 2
4

  • .. doctest:: directive

    reStructuredText:

    .. doctest::

   >>> 2 + 2
   4

    Markdown (requires myst-parser):

    ```{doctest}
>>> 2 + 2
4
```

Usage#

The doctest_docutils module preserves standard library’s usage conventions:

reStructuredText#
$ python -m doctest_docutils README.rst -v

That’s what doctest does by design.

Markdown#

If you install myst-parser, doctest will run on .md files.

$ python -m doctest_docutils README.md -v

pytest plugin#

This plugin disables pytest’s standard doctest plugin.

This plugin integrates with the doctest_docutils module with pytest to enable seamless testing of docs, conftest.py fixtures and all.

$ pytest docs/

Like the above module, it supports docutils’ own doctest_block and a basic .. doctest:: directive.

See more: https://gp-libs.git-pull.com/doctest/pytest.html

sphinx plugins#

Plain-text issue linker (linkify-issues)#

We need to parse plain text, e.g. #99999, to point to the project tracker at https://github.com/git-pull/gp-libs/issues/99999. This way the markdown looks good anywhere you render it, including GitHub and GitLab.

Configuration#

In your conf.py:

  1. Add 'linkify_issues' to extensions

    extensions = [
    # ...
    "linkify_issues",
]

  2. Configure your issue URL, issue_url_tpl:

    # linkify_issues
issue_url_tpl = 'https://github.com/git-pull/gp-libs/issues/{issue_id}'

    The config variable is formatted via str.format() where issue_id is 42 if the text is #42.

See more: https://gp-libs.git-pull.com/linkify_issues/

Install#

$ pip install --user gp-libs

Developmental releases#

You can test the unpublished version of g before its released.

  • pip:

    $ pip install --user --upgrade --pre gp-libs

Minimum requirements#

To lift the development burden of supporting legacy APIs, as this package is lightly used, minimum constraints have been pinned:

  • docutils: 0.20.1+

  • myst-parser: 2.0.0+

If you have even passing interested in supporting legacy versions, file an issue on the tracker.

More information#

Docs Build Status