gp-libs · ¶
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:
doctest_docutils
module: Same specification asdoctest
, but can parse reStructuredText and markdownpytest_doctest_docutils
: Pytest plugin, collects test items for pytest for reStructuredText and markdown filesThis 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::
directivereStructuredText:
.. 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.
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:
Add
'linkify_issues'
toextensions
extensions = [ # ... "linkify_issues", ]
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()
whereissue_id
is42
if the text is #42.
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¶
Python support: >= 3.8, pypy
Changelog: https://gp-libs.git-pull.com/history.html
Test Coverage: https://codecov.io/gh/git-pull/gp-libs
License: MIT.