Internal utilities for projects following git-pull python package spec
Project description
gp-libs · 
Incubating / dogfooding some sphinx extensions and pytest plugins on git-pull projects, e.g. cihai, vcs-python, or tmux-python.
doctest helpers (for docutils)
Two parts:
- doctest module: Same specification as doctest, but can parse reStructuredText and markdown
- pytest plugin: Collects pytest for reStructuredText and markdown files
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/
Writing doctests
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 ```
Test your docs
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 above module.
$ 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:
-
Add
'linkify_issues'toextensionsextensions = [ # ... "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 {meth}
str.formatwhereissue_idis42if the text is #42.
See more: https://gp-libs.git-pull.com/linkify_issues/
Table of contents for autodoc
sphinx.ext.autodoc doesn't link objects in the table of contents. So we need a
plugin to help.
See more: https://gp-libs.git-pull.com/sphinx_toctree_autodoc_fix/
Configuration
-
Add
'sphinx_toctree_autodoc_fix'toextensionsextensions = [ # ... "sphinx_toctree_autodoc_fix", ]
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
More information
- Python support: >= 3.7, pypy
- Source: https://github.com/git-pull/gp-libs
- Docs: https://gp-libs.git-pull.com
- Changelog: https://gp-libs.git-pull.com/history.html
- Issues: https://github.com/git-pull/gp-libs/issues
- Test Coverage: https://codecov.io/gh/git-pull/gp-libs
- pypi: https://pypi.python.org/pypi/gp-libs
- License: MIT.
