Skip to content

Commit 3662f83

Browse files
domdfcodingdomdfcoding
committed
Updated docs.
1 parent 456fa21 commit 3662f83

File tree

7 files changed

+102
-96
lines changed

7 files changed

+102
-96
lines changed

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ repos:
5555

5656

5757
- repo: https://github.com/domdfcoding/yapf-isort
58-
rev: v0.3.0
58+
rev: v0.3.2
5959
hooks:
6060
- id: yapf-isort
6161
exclude: ^(doc-source/conf|__pkginfo__|make_conda_recipe|setup)\.py$

‎coverage_pyver_pragma/__init__.py‎

Lines changed: 22 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22
#
33
# __init__.py
44
"""
5-
Plugin for Coverage.py to selectively ignore branches depending on the Python version.
5+
Plugin for `Coverage.py <https://coverage.readthedocs.io/en/coverage-5.3/>`_
6+
to selectively ignore branches depending on the Python version.
67
"""
78
#
89
# Copyright (c) 2020 Dominic Davis-Foster <dominic@davis-foster.co.uk>
@@ -33,6 +34,15 @@
3334
# 3rd party
3435
import coverage # type: ignore
3536

37+
__all__ = [
38+
"regex_main",
39+
"Version",
40+
"make_regexes",
41+
"PyVerPragmaPlugin",
42+
"make_not_exclude_regexs",
43+
"coverage_init",
44+
]
45+
3646
if TYPE_CHECKING:
3747

3848
# stdlib
@@ -50,12 +60,7 @@
5060

5161
class Version(NamedTuple):
5262
"""
53-
:class:`~typing.NamedTuple` with the same elements as :func:`sys.version_info`.
54-
55-
:type major: int
56-
:type minor: int
57-
:type micro: int
58-
63+
:class:`~typing.NamedTuple` with the same elements as :py:data:`sys.version_info`.
5964
"""
6065

6166
major: int
@@ -71,14 +76,12 @@ def make_regexes(
7176
current_implementation: str,
7277
) -> List[Pattern]:
7378
"""
74-
Generate a list of regular expressions to match all valid ignores for the given Python version.
79+
Generates a list of regular expressions to match all valid ignores for the given Python version.
7580
7681
:param version_tuple: The Python version.
77-
:type version_tuple: :class:`~typing.NamedTuple` with the attributes ``major`` and ``minor``.
82+
:type version_tuple: :class:`~typing.NamedTuple` with the attributes ``major`` and ``minor``
7883
:param current_platform:
79-
:type current_platform: str
8084
:param current_implementation:
81-
:type current_implementation: str
8285
8386
:return: List of regular expressions.
8487
"""
@@ -134,7 +137,8 @@ def make_regexes(
134137

135138
class PyVerPragmaPlugin(coverage.CoveragePlugin):
136139
"""
137-
Plugin for Coverage.py to selectively ignore branches depending on the Python version.
140+
Plugin for `Coverage.py <https://coverage.readthedocs.io/en/coverage-5.3/>`_
141+
to selectively ignore branches depending on the Python version.
138142
"""
139143

140144
def configure(self, config: Any) -> None:
@@ -171,6 +175,12 @@ def make_not_exclude_regexs(
171175
current_platform: str,
172176
current_implementation: str,
173177
) -> List[Pattern]:
178+
"""
179+
Generates a list of regular expressions for lines that should not be excluded.
180+
181+
:param current_platform:
182+
:param current_implementation:
183+
"""
174184

175185
return [
176186
re.compile(
@@ -185,12 +195,7 @@ def coverage_init(reg, options):
185195
Initialise the plugin.
186196
187197
:param reg:
188-
:type reg:
189198
:param options:
190-
:type options:
191-
192-
:return:
193-
:rtype:
194199
"""
195200

196201
reg.add_configurer(PyVerPragmaPlugin()) # pragma: no cover

‎doc-source/conf.py‎

Lines changed: 39 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
sys.path.append(os.path.abspath('.'))
1111
sys.path.append(os.path.abspath('..'))
1212

13+
# this package
1314
from __pkginfo__ import __version__
1415

1516
# User-configurable lines
@@ -19,7 +20,6 @@
1920
github_repository = "coverage_pyver_pragma"
2021
github_url = f"https://github.com/{github_username}/{github_repository}"
2122

22-
2323
rst_prolog = f""".. |pkgname| replace:: coverage_pyver_pragma
2424
.. |pkgname2| replace:: ``coverage_pyver_pragma``
2525
.. |browse_github| replace:: `Browse the GitHub Repository <{github_url}>`__
@@ -34,22 +34,22 @@
3434
package_root = "coverage_pyver_pragma"
3535

3636
extensions = [
37-
'sphinx_toolbox',
38-
'sphinx_toolbox.more_autodoc',
39-
'sphinx_toolbox.more_autosummary',
40-
'sphinx_toolbox.tweaks.param_dash',
41-
'sphinx.ext.intersphinx',
42-
'sphinx.ext.mathjax',
43-
'sphinxcontrib.httpdomain',
44-
'sphinxcontrib.extras_require',
45-
'sphinx.ext.todo',
46-
'sphinxemoji.sphinxemoji',
47-
'notfound.extension',
48-
'sphinx_copybutton',
49-
'sphinxcontrib.default_values',
50-
'sphinxcontrib.toctree_plus',
51-
'seed_intersphinx_mapping',
52-
]
37+
'sphinx_toolbox',
38+
'sphinx_toolbox.more_autodoc',
39+
'sphinx_toolbox.more_autosummary',
40+
'sphinx_toolbox.tweaks.param_dash',
41+
'sphinx.ext.intersphinx',
42+
'sphinx.ext.mathjax',
43+
'sphinxcontrib.httpdomain',
44+
'sphinxcontrib.extras_require',
45+
'sphinx.ext.todo',
46+
'sphinxemoji.sphinxemoji',
47+
'notfound.extension',
48+
'sphinx_copybutton',
49+
'sphinxcontrib.default_values',
50+
'sphinxcontrib.toctree_plus',
51+
'seed_intersphinx_mapping',
52+
]
5353

5454
sphinxemoji_style = 'twemoji'
5555
todo_include_todos = bool(os.environ.get("SHOW_TODOS", 0))
@@ -110,29 +110,31 @@
110110
}
111111

112112
add_module_names = False
113-
114-
113+
hide_none_rtype = True
114+
115+
116+
autodoc_exclude_members = [ # Exclude "standard" methods.
117+
"__dict__",
118+
"__class__",
119+
"__dir__",
120+
"__weakref__",
121+
"__module__",
122+
"__annotations__",
123+
"__orig_bases__",
124+
"__parameters__",
125+
"__subclasshook__",
126+
"__init_subclass__",
127+
"__attrs_attrs__",
128+
"__init__",
129+
"__new__",
130+
"__getnewargs__",
131+
"__abstractmethods__",
132+
"__hash__",
133+
]
115134
autodoc_default_options = {
116135
'members': None, # Include all members (methods).
117136
'special-members': None,
118137
"autosummary": None,
119138
"show-inheritance": None,
120-
'exclude-members': ','.join([ # Exclude "standard" methods.
121-
"__dict__",
122-
"__class__",
123-
"__dir__",
124-
"__weakref__",
125-
"__module__",
126-
"__annotations__",
127-
"__orig_bases__",
128-
"__parameters__",
129-
"__subclasshook__",
130-
"__init_subclass__",
131-
"__attrs_attrs__",
132-
"__init__",
133-
"__new__",
134-
"__getnewargs__",
135-
"__abstractmethods__",
136-
"__hash__",
137-
]),
139+
'exclude-members': ','.join(autodoc_exclude_members),
138140
}

‎doc-source/docs.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
===========================
1+
==================
22
API Reference
3-
===========================
3+
==================
44

55
.. automodule:: coverage_pyver_pragma
66
:members:

‎doc-source/index.rst‎

Lines changed: 10 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
######################
1+
======================
22
coverage_pyver_pragma
3-
######################
3+
======================
44

55
.. start short_desc
66
@@ -108,19 +108,6 @@ coverage_pyver_pragma
108108

109109
.. end shields
110110
111-
Installation
112-
---------------
113-
114-
.. start installation
115-
116-
.. installation:: coverage_pyver_pragma
117-
:pypi:
118-
:github:
119-
:anaconda:
120-
:conda-channels: domdfcoding, conda-forge
121-
122-
.. end installation
123-
124111
.. toctree::
125112
:hidden:
126113

@@ -130,8 +117,14 @@ Installation
130117
:maxdepth: 3
131118
:caption: Documentation
132119

133-
usage
134-
API Reference<docs>
120+
installation
121+
syntax
122+
docs
123+
124+
.. toctree::
125+
:maxdepth: 3
126+
:caption: Contributing
127+
135128
contributing
136129
Source
137130

‎doc-source/installation.rst‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
=============
2+
Installation
3+
=============
4+
5+
.. installation:: coverage_pyver_pragma
6+
:pypi:
7+
:github:
8+
:anaconda:
9+
:conda-channels: domdfcoding, conda-forge
10+
11+
Then enable the plugin in your coverage configuration.
12+
The ``.coveragerc`` file in the repository root should contain the following options:
13+
14+
.. code-block:: ini
15+
16+
[run]
17+
plugins =
18+
coverage_pyver_pragma
19+
20+
21+
Alternatively you can put the configuration in the ``setup.cfg`` or ``tox.ini`` files like so:
22+
23+
.. code-block:: ini
24+
25+
[coverage:run]
26+
plugins =
27+
coverage_pyver_pragma

‎doc-source/usage.rst‎ renamed to ‎doc-source/syntax.rst‎

Lines changed: 1 addition & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,6 @@
11
=========
2-
Usage
3-
=========
4-
5-
The ``.coveragerc`` file in the repository root should contain the following options:
6-
7-
.. code-block:: ini
8-
9-
[run]
10-
plugins =
11-
coverage_pyver_pragma
12-
13-
14-
Alternatively you can put the configuration in the ``setup.cfg`` or ``tox.ini`` files like so:
15-
16-
.. code-block:: ini
17-
18-
[coverage:run]
19-
plugins =
20-
coverage_pyver_pragma
21-
22-
232
Syntax
24-
--------
3+
=========
254

265
To ignore when running with versions of Python above, for instance, Python 3.6:
276

0 commit comments

Comments
 (0)