Improve docs layout.

Author: domdfcoding

coverage_pyver_pragma/grammar.py

@@ -16,14 +16,15 @@
 (: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``.
+A series of tags without keywords between them are evaluated with ``AND``.
 
 .. 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 ``>=``.
 
-**Examples:**
+
+:bold-title:`Example:`
 
 .. parsed-literal::
 
@@ -39,7 +40,8 @@
 A ``PLATFORM_TAG`` comprises a single word which will be compared (ignoring case)
 with the output of :func:`platform.system`.
 
-**Examples:**
+
+:bold-title:`Example:`
 
 .. parsed-literal::
 
@@ -59,7 +61,8 @@
 An ``IMPLEMENTATION_TAG`` comprises a single word which will be compared (ignoring case)
 with the output of :func:`platform.python_implementation`.
 
-**Examples:**
+
+:bold-title:`Example:`
 
 .. parsed-literal::
 
@@ -68,6 +71,7 @@
 	IronPython
 	Jython
 
+
 Examples
 -----------
 
@@ -102,6 +106,7 @@
 API Reference
 ----------------
 
+.. automodulesumm:: coverage_pyver_pragma.grammar
 """  # noqa: D400
 #
 #  Copyright © 2021 Dominic Davis-Foster <dominic@davis-foster.co.uk>
@@ -185,7 +190,7 @@ class VersionTag(packaging.specifiers.SpecifierSet):
 	A ``VERSION_TAG`` comprises an optional comparator (one of ``<=``, ``<``, ``>=``, ``>``),
 	a version specifier in the form ``pyXX``, and an optional ``+`` to indicate ``>=``.
 
-	**Examples:**
+	:bold-title:`Examples:`
 
 	.. parsed-literal::
 
@@ -231,7 +236,7 @@ class PlatformTag(str):
 	A ``PLATFORM_TAG`` comprises a single word which will be compared (ignoring case)
 	with the output of :func:`platform.system`.
 
-	**Examples:**
+	:bold-title:`Examples:`
 
 	.. parsed-literal::
 
@@ -268,7 +273,7 @@ class ImplementationTag(str):
 	An ``IMPLEMENTATION_TAG`` comprises a single word which will be compared (ignoring case)
 	with the output of :func:`platform.python_implementation`.
 
-	**Examples:**
+	:bold-title:`Examples:`
 
 	.. parsed-literal::
 
@@ -278,6 +283,8 @@ class ImplementationTag(str):
 		Jython
 
 	:param tokens:
+
+	.. latex:vspace:: -10px
 	"""
 
 	__slots__ = ()
@@ -409,7 +416,7 @@ def __bool__(self):
 				)
 		)
 """
-The ``coverage_pyver_pragma`` expression grammar.
+The :mod:`coverage_pyver_pragma` expression grammar.
 
 This can be used to parse an expression outside of the coverage context.
 """

doc-source/api.rst

@@ -2,4 +2,7 @@
 Public API
 =============
 
+.. autosummary-widths:: 6/16
+	:html: 35/100
+
 .. automodule:: coverage_pyver_pragma

doc-source/conf.py

@@ -66,5 +66,16 @@
 		}
 
 latex_elements = {
-		"fncychap": "\\usepackage[Bjarne]{fncychap}\n\\ChNameAsIs\n\\ChTitleAsIs\n",
+		"printindex": "\\begin{flushleft}\n\\printindex\n\\end{flushleft}",
+		"tableofcontents": "\\pdfbookmark[0]{\\contentsname}{toc}\\sphinxtableofcontents",
 		}
+
+
+def setup(app):
+	# 3rd party
+	from sphinx_toolbox.latex import better_header_layout
+
+	app.connect("config-inited", lambda app, config: better_header_layout(config))
+
+
+toctree_plus_types.add("envvar")

doc-source/configuration.rst

@@ -16,7 +16,7 @@ For instance, you are generating a report from a ``.coverage`` file produced on
 
 	Defaults to the output of :func:`'.'.join(platform.python_version_tuple()[:2]) <platform.python_version_tuple>`.
 
-	**Example:**
+	:bold-title:`Example:`
 
 	.. prompt:: bash
 
@@ -29,7 +29,7 @@ For instance, you are generating a report from a ``.coverage`` file produced on
 
 	Defaults to the output of :func:`platform.system`.
 
-	**Example:**
+	:bold-title:`Example:`
 
 	.. prompt:: bash
 
@@ -43,7 +43,7 @@ For instance, you are generating a report from a ``.coverage`` file produced on
 
 	Defaults to the output of :func:`platform.python_implementation`.
 
-	**Example:**
+	:bold-title:`Example:`
 
 	.. prompt:: bash
 

doc-source/requirements.txt

@@ -1,4 +1,4 @@
-git+https://github.com/sphinx-toolbox/html-section.git
+git+https://github.com/sphinx-toolbox/sphinx-toolbox-experimental.git
 autodocsumm>=0.2.0
 default-values>=0.4.2
 extras-require>=0.2.0
@@ -11,7 +11,7 @@ sphinx-notfound-page>=0.5
 sphinx-prompt>=1.1.0
 sphinx-pyproject>=0.1.0
 sphinx-tabs>=1.1.13
-sphinx-toolbox>=2.9.0
+sphinx-toolbox>=2.12.0
 sphinxcontrib-httpdomain>=1.7.0
 sphinxemoji>=0.1.6
 toctree-plus>=0.1.0

doc-source/syntax.rst

@@ -2,4 +2,8 @@
 Syntax
 =========
 
+.. autosummary-widths:: 6/16
+	:html: 3/10
+
 .. automodule:: coverage_pyver_pragma.grammar
+	:no-autosummary:

pyproject.toml

@@ -54,6 +54,7 @@ extensions = [
     "sphinx_toolbox.more_autosummary",
     "sphinx_toolbox.documentation_summary",
     "sphinx_toolbox.tweaks.param_dash",
+    "sphinx_toolbox.tweaks.latex_layout",
     "sphinx_toolbox.tweaks.latex_toc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
@@ -67,7 +68,9 @@ extensions = [
     "sphinxcontrib.toctree_plus",
     "sphinx_debuginfo",
     "seed_intersphinx_mapping",
-    "html_section",
+    "sphinx_toolbox_experimental.html_section",
+    "sphinx_toolbox_experimental.autosummary_widths",
+    "sphinx_toolbox_experimental.needspace",
 ]
 sphinxemoji_style = "twemoji"
 gitstamp_fmt = "%d %b %Y"
@@ -89,7 +92,6 @@ toctree_plus_types = [
     "exception",
     "flag",
     "function",
-    "method",
     "namedtuple",
     "protocol",
     "role",

repo_helper.yml

@@ -45,7 +45,12 @@ keywords:
   - coverage
 
 extra_sphinx_extensions:
-  - html_section
+  - sphinx_toolbox_experimental.html_section
+  - sphinx_toolbox_experimental.autosummary_widths
+  - sphinx_toolbox_experimental.needspace
 
 exclude_files:
   - contributing
+
+sphinx_conf_epilogue:
+  - toctree_plus_types.add("envvar")