Improve docs layout with the LaTeX builder.

Author: domdfcoding

coverage_pyver_pragma/__init__.py

@@ -65,8 +65,6 @@ def evaluate_exclude(expression: str) -> bool:
 
 	.. versionadded:: 0.2.4
 
-	|
-
 	:param expression:
 	"""
 

coverage_pyver_pragma/grammar.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 #
 #  grammar.py
-"""
+r"""
 .. versionadded:: 0.2.0
 
 As with ``coverage.py``, lines are marked with comments in the form::
@@ -50,6 +50,9 @@
 
 If the current platform cannot be determined all strings are treated as :py:obj:`True`.
 
+.. raw:: latex
+
+	\clearpage
 
 .. py:data:: IMPLEMENTATION_TAG
 
@@ -68,11 +71,11 @@
 Examples
 -----------
 
-ignore if the Python version is less than or equal to 3.7::
+Ignore if the Python version is less than or equal to 3.7::
 
 	# pragma: no cover (<=py37)
 
-ignore if running on Python 3.9::
+Ignore if running on Python 3.9::
 
 	# pragma: no cover (py39)
 
@@ -92,6 +95,10 @@
 
 	# pragma: no cover (!CPython)
 
+.. raw:: latex
+
+	\clearpage
+
 API Reference
 ----------------
 

doc-source/_templates/sidebar/navigation.html

@@ -5,90 +5,19 @@
 # stdlib
 import os
 import re
+import sys
 
 # 3rd party
 from sphinx_pyproject import SphinxConfig
 
-config = SphinxConfig()
-
-github_username = "python-coincidence"
-github_repository = "coverage_pyver_pragma"
-author = "Dominic Davis-Foster"
-project = "coverage-pyver-pragma"
-copyright = "2020-2021 Dominic Davis-Foster"
-language = "en"
-package_root = "coverage_pyver_pragma"
-extensions = [
-		"sphinx_toolbox",
-		"sphinx_toolbox.more_autodoc",
-		"sphinx_toolbox.more_autosummary",
-		"sphinx_toolbox.documentation_summary",
-		"sphinx_toolbox.tweaks.param_dash",
-		"sphinx_toolbox.tweaks.latex_toc",
-		"sphinx.ext.intersphinx",
-		"sphinx.ext.mathjax",
-		"sphinxcontrib.httpdomain",
-		"sphinxcontrib.extras_require",
-		"sphinx.ext.todo",
-		"sphinxemoji.sphinxemoji",
-		"notfound.extension",
-		"sphinx_copybutton",
-		"sphinxcontrib.default_values",
-		"sphinxcontrib.toctree_plus",
-		"sphinx_debuginfo",
-		"seed_intersphinx_mapping",
-		]
-sphinxemoji_style = "twemoji"
-gitstamp_fmt = "%d %b %Y"
-templates_path = ["_templates"]
-html_static_path = ["_static"]
-source_suffix = ".rst"
-master_doc = "index"
-suppress_warnings = ["image.nonlocal_uri"]
-pygments_style = "default"
-html_theme = "furo"
-html_theme_path = ["../.."]
-html_show_sourcelink = True
-toctree_plus_types = [
-		"class",
-		"confval",
-		"data",
-		"directive",
-		"enum",
-		"exception",
-		"flag",
-		"function",
-		"method",
-		"namedtuple",
-		"protocol",
-		"role",
-		"typeddict",
-		]
-add_module_names = False
-hide_none_rtype = True
-all_typevars = True
-overloads_location = "bottom"
-documentation_summary = "Plugin for Coverage.py to selectively ignore branches depending on the Python version."
-autodoc_exclude_members = [
-		"__dict__",
-		"__class__",
-		"__dir__",
-		"__weakref__",
-		"__module__",
-		"__annotations__",
-		"__orig_bases__",
-		"__parameters__",
-		"__subclasshook__",
-		"__init_subclass__",
-		"__attrs_attrs__",
-		"__init__",
-		"__new__",
-		"__getnewargs__",
-		"__abstractmethods__",
-		"__hash__",
-		]
-
-github_url = f"https://github.com/{github_username}/{github_repository}"
+sys.path.append('.')
+
+config = SphinxConfig(globalns=globals())
+project = config["project"]
+author = config["author"]
+documentation_summary = config.description
+
+github_url = "https://github.com/{github_username}/{github_repository}".format_map(config)
 
 rst_prolog = f""".. |pkgname| replace:: coverage_pyver_pragma
 .. |pkgname2| replace:: ``coverage_pyver_pragma``
@@ -126,12 +55,16 @@
 man_pages = [("index", slug, project, [author], 1)]
 texinfo_documents = [("index", slug, project, author, slug, project, "Miscellaneous")]
 
-toctree_plus_types = set(toctree_plus_types)
+toctree_plus_types = set(config["toctree_plus_types"])
 
 autodoc_default_options = {
 		"members": None,  # Include all members (methods).
 		"special-members": None,
 		"autosummary": None,
 		"show-inheritance": None,
-		"exclude-members": ','.join(autodoc_exclude_members),
+		"exclude-members": ','.join(config["autodoc_exclude_members"]),
+		}
+
+latex_elements = {
+		"fncychap": "\\usepackage[Bjarne]{fncychap}\n\\ChNameAsIs\n\\ChTitleAsIs\n",
 		}

doc-source/conf.py

@@ -0,0 +1,62 @@
+=================
+Configuration
+=================
+
+.. versionadded:: 0.3.0
+
+When using Coverage.py's `reporting commands <https://coverage.readthedocs.io/en/coverage-5.5/cmd.html?highlight=report#coverage-summary-coverage-report>`_
+it may be desirable to generate a report for a different Python version / implementation / platform to the current one.
+For instance, you are generating a report from a ``.coverage`` file produced on PyPy 3.6 on Windows, but you are running CPython 3.8 on Linux.
+
+``coverage_pyver_pragma`` provides three environment variables which can be used to set the target version and platform.
+
+.. envvar:: COV_PYTHON_VERSION
+
+	Sets the Python version. Must be in the form :file:`{<major>}.{<minor>}`.
+
+	Defaults to the output of :func:`'.'.join(platform.python_version_tuple()[:2]) <platform.python_version_tuple>`.
+
+	**Example:**
+
+	.. prompt:: bash
+
+		COV_PYTHON_VERSION=3.6 coverage report
+
+.. envvar:: COV_PLATFORM
+
+	Sets the Python platform.
+	Must be a string which matches the output of :func:`platform.system` on the desired platform.
+
+	Defaults to the output of :func:`platform.system`.
+
+	**Example:**
+
+	.. prompt:: bash
+
+		COV_PLATFORM=Windows coverage report
+
+.. envvar:: COV_PYTHON_IMPLEMENTATION
+
+	Sets the Python implementation.
+	Must be a string which matches the output of
+	:func:`platform.python_implementation` with the desired implementation.
+
+	Defaults to the output of :func:`platform.python_implementation`.
+
+	**Example:**
+
+	.. prompt:: bash
+
+		COV_PYTHON_IMPLEMENTATION=PyPy coverage report
+
+If you generate your coverage reports through `tox <https://tox.readthedocs.io/en/latest/>`_
+you should configure `passenv <https://tox.readthedocs.io/en/latest/config.html?highlight=setenv#conf-passenv>`_
+to ensure the environment variables are passed through:
+
+.. code-block:: ini
+
+	[testenv]
+	passenv =
+	    COV_PYTHON_VERSION
+	    COV_PLATFORM
+	    COV_PYTHON_IMPLEMENTATION

doc-source/configuration.rst

@@ -122,18 +122,11 @@ coverage_pyver_pragma
 
 .. end shields
 
-Installation
----------------
+Contents
+----------
 
-.. start installation
+.. html-section::
 
-.. installation:: coverage_pyver_pragma
-	:pypi:
-	:github:
-	:anaconda:
-	:conda-channels: conda-forge, domdfcoding
-
-.. end installation
 
 .. toctree::
 	:hidden:
@@ -142,18 +135,21 @@ Installation
 
 .. toctree::
 	:maxdepth: 3
-	:caption: Documentation
 
 	installation
+	configuration
 	syntax
 	api
+	Source
 
-.. toctree::
-	:maxdepth: 3
-	:caption: Contributing
 
-	contributing
-	Source
+.. sidebar-links::
+	:caption: Links
+	:github:
+	:pypi: coverage_pyver_pragma
+
+	Contributing Guide <https://contributing-to-coincidence.readthedocs.io/en/latest/>
+
 
 .. start links