Update docs.

Author: domdfcoding

coverage_pyver_pragma/grammar.py

@@ -2,16 +2,23 @@
 #
 #  grammar.py
 """
-The expression grammar for ``coverage_pyver_pragma``.
-
 .. versionadded:: 0.2.0
 
-Each expression consists of one or more tags (``VERSION_TAG``, ``PLATFORM_TAG`` or ``IMPLEMENTATION_TAG``).
+As with ``coverage.py``, lines are marked with comments in the form::
+
+	# pragma: no cover
+
+With ``coverage_pyver_pragma``, the comment may be followed with an expression enclosed in parentheses::
+
+	# pragma: no cover (<=py38 and !Windows)
+
+Each expression consists of one or more tags
+(:py:data:`VERSION_TAG`, :py:data:`PLATFORM_TAG` or :py:data:`IMPLEMENTATION_TAG`).
 The tags can be joined with the keywords ``AND``, ``OR`` and ``NOT``, with the exclamation mark ``!`` implying ``NOT``.
 Parentheses can be used to group sub expressions.
+A series of tags without keywords in between them are evaluated with ``AND``.
 
-``VERSION_TAG``
--------------------
+.. py:data:: VERSION_TAG
 
 A ``VERSION_TAG`` comprises an optional comparator (one of ``<=``, ``<``, ``>=``, ``>``),
 a version specifier in the form ``pyXX``, and an optional ``+`` to indicate ``>=``.
@@ -27,8 +34,7 @@
 	py34+  # equivalent to >=py34
 
 
-``PLATFORM_TAG``
--------------------
+.. py:data::  PLATFORM_TAG
 
 A ``PLATFORM_TAG`` comprises a single word which will be compared (ignoring case)
 with the output of :func:`platform.system`.
@@ -45,8 +51,7 @@
 If the current platform cannot be determined all strings are treated as :py:obj:`True`.
 
 
-``IMPLEMENTATION_TAG``
------------------------
+.. py:data:: IMPLEMENTATION_TAG
 
 An ``IMPLEMENTATION_TAG`` comprises a single word which will be compared (ignoring case)
 with the output of :func:`platform.python_implementation`.
@@ -63,10 +68,32 @@
 Examples
 -----------
 
-.. parsed-literal::
+ignore if the Python version is less than or equal to 3.7::
+
+	# pragma: no cover (<=py37)
+
+ignore if running on Python 3.9::
+
+	# pragma: no cover (py39)
+
+Ignore if the Python version is greater than 3.6 and it's not running on PyPy::
+
+	# pragma: no cover (>py36 and !PyPy)
 
-	>py36 and !PyPy
-	Windows and <py38
+Ignore if the Python version is less than 3.8 and it's running on Windows::
+
+	# pragma: no cover (Windows and <py38)
+
+Ignore when not running on macOS (Darwin)::
+
+	# pragma: no cover (!Darwin)
+
+Ignore when not running on CPython::
+
+	# pragma: no cover (!CPython)
+
+API Reference
+----------------
 
 """
 #
@@ -106,6 +133,7 @@
 		Literal,
 		OneOrMore,
 		Optional,
+		ParserElement,
 		ParseResults,
 		Word,
 		infixNotation,
@@ -200,8 +228,8 @@ class PlatformTag(str):
 
 	__slots__ = ()
 
-	def __new__(cls, token: ParseResults):  # noqa: D102
-		return super().__new__(cls, str(token["platform"]))
+	def __new__(cls, tokens: ParseResults):  # noqa: D102
+		return super().__new__(cls, str(tokens["platform"]))
 
 	def __repr__(self) -> str:  # pragma: no cover
 		return f"<{self.__class__.__name__}({str(self)!r})>"
@@ -353,7 +381,7 @@ def __bool__(self):
 
 ELEMENTS = VERSION_TAG | PLATFORM_TAG | IMPLEMENTATION_TAG
 
-GRAMMAR = OneOrMore(
+GRAMMAR: ParserElement = OneOrMore(
 		infixNotation(
 				ELEMENTS,
 				[
@@ -363,3 +391,8 @@ def __bool__(self):
 						]
 				)
 		)
+"""
+The ``coverage_pyver_pragma`` expression grammar.
+
+This can be used to parse an expression outside of the coverage context.
+"""

doc-source/api.rst

@@ -0,0 +1,5 @@
+=============
+Public API
+=============
+
+.. automodule:: coverage_pyver_pragma

doc-source/conf.py

@@ -62,6 +62,7 @@
 intersphinx_mapping = {
 		"python": ("https://docs.python.org/3/", None),
 		"sphinx": ("https://www.sphinx-doc.org/en/stable/", None),
+		"pyparsing": ("https://pyparsing-docs.readthedocs.io/en/latest", None),
 		}
 
 html_theme = "domdf_sphinx_theme"

doc-source/docs.rst

@@ -103,7 +103,7 @@ coverage_pyver_pragma
 	:alt: GitHub top language
 
 .. |commits-since| github-shield::
-	:commits-since: v0.0.6
+	:commits-since: v0.2.0
 	:alt: GitHub commits since tagged version
 
 .. |commits-latest| github-shield::
@@ -147,7 +147,7 @@ Installation
 
 	installation
 	syntax
-	docs
+	api
 
 .. toctree::
 	:maxdepth: 3

doc-source/index.rst

@@ -1,7 +1,7 @@
 autodocsumm>=0.2.0
 default-values>=0.4.2
-domdf-sphinx-theme>=0.3.0
 extras-require>=0.2.0
+furo>=2020.11.19b18
 seed-intersphinx-mapping>=0.3.1
 sphinx<3.4.0,>=3.0.3
 sphinx-copybutton>=0.2.12

doc-source/requirements.txt

@@ -2,46 +2,4 @@
 Syntax
 =========
 
-To ignore when running with versions of Python above, for instance, Python 3.6:
-
-.. code-block:: python
-
-	# pragma: no cover (>py36)
-
-You can also ignore for a specific version of Python:
-
-.. code-block:: python
-
-	# pragma: no cover (py36)
-
-Other examples:
-
-.. code-block:: python
-
-	# pragma: no cover (<py38)
-	# pragma: no cover (<=py38)
-	# pragma: no cover (>=py38)
-	# pragma: no cover (py38+)
-
-
-You can also exclude lines based on platform. For example, to exclude a line when the platform is not Windows:
-
-.. code-block:: python
-
-	# pragma: no cover (!Windows)
-
-You can also exclude lines based on Python implementation. For example, to exclude a line when the implementation is not CPython:
-
-.. code-block:: python
-
-	# pragma: no cover (!CPython)
-
-These can also be combined with the Python version:
-
-.. code-block:: python
-
-	# pragma: no cover (<=py36 !Windows !CPython)
-
-This will ignore coverage (or lack thereof) for the branch if all three conditions are satisfied
-(Python 3.6 or earlier AND not Windows AND not CPython).
-It is not currently possible to ignore a branch if EITHER condition is true.
+.. automodule:: coverage_pyver_pragma.grammar

doc-source/syntax.rst

@@ -33,3 +33,6 @@ sphinx_html_theme: domdf_sphinx_theme
 tox_unmanaged:
   - coverage:run
   - testenv:coverage
+
+intersphinx_mapping:
+  - "'pyparsing': ('https://pyparsing-docs.readthedocs.io/en/latest', None)"