Improve documentation and try furo (#2180)

Author: gaborbernat

docs/_static/custom.css

@@ -1,32 +1,7 @@
-.wy-nav-content {
-  padding: 1em;
-  max-width: 100%;
-}
-
-/* Reduce whitespace on the inline-code snippets and add softer corners */
-.rst-content code {
-  padding: 2px 3px;
-  border-radius: 3px;
-}
-
-dl {
-  /*margin-bottom: 0!important;*/
-}
-dt {
-  display: inline !important;
-  padding: 3px;
-}
-dd {
-  margin-bottom: 2px!important;
-}
-.rst-content dd p {
-  margin-bottom: 0px;
-}
-
-/* Reduce whitespace before enumeration */
-.section p {
-  margin-bottom: 12px;
-}
-.section ol {
-  margin-bottom: 12px !important;
+blockquote {
+    border-left: none;
+    font-style: normal;
+    margin-left: 1.5rem;
+    margin-right: 0;
+    padding: 0;
 }

docs/changelog/1881.doc.rst

@@ -0,0 +1,3 @@
+Adopt furo theme, update our state diagram and description in user docs (SVG + light/dark variant), split
+the Python API into its own page from under the plugin page, and document plugin adoption under the ``tox-dev``
+organization - by :user:`gaborbernat`.

docs/conf.py

@@ -6,7 +6,6 @@
 from subprocess import check_output
 from typing import Any, cast
 
-import sphinx_rtd_theme
 from docutils.nodes import Element, Node, Text, container, fully_normalize_name, literal, paragraph, reference, strong
 from docutils.parsers.rst.directives import flag, unchanged, unchanged_required
 from docutils.parsers.rst.states import RSTState, RSTStateMachine
@@ -51,23 +50,16 @@
 project = name
 today_fmt = "%B %d, %Y"
 
-html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme = "furo"
 html_theme_options = {
-    "canonical_url": "https://tox.readthedocs.io/en/latest/",
-    "logo_only": False,
-    "display_version": True,
-    "prev_next_buttons_location": "bottom",
-    "collapse_navigation": False,
-    "sticky_navigation": True,
-    "navigation_depth": 6,
-    "includehidden": True,
+    "navigation_with_keys": True,
 }
+html_title = "tox 4 - rewrite"
 html_static_path = ["_static"]
+html_css_files = ["css/custom.css"]
 html_last_updated_fmt = datetime.now().isoformat()
 html_logo = "_static/img/tox.svg"
 html_favicon = "_static/img/toxfavi.ico"
-htmlhelp_basename = "Pastedoc"
 
 autoclass_content = "class"
 autodoc_member_order = "bysource"
@@ -148,7 +140,6 @@ def resolve_xref(
     app.connect("autodoc-skip-member", skip_member)
     app.connect("autodoc-process-signature", process_signature, priority=400)
     app.add_domain(PatchedPythonDomain, override=True)
-    app.add_css_file("custom.css")
 
     class ToxConfig(SphinxDirective):
         name = "conf"

docs/config.rst

@@ -195,8 +195,9 @@ Core
 
     Indicates where the packaging root file exists (historically setup.py file or pyproject.toml now).
 
-Python
-~~~~~~
+Python language core options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. conf::
    :keys: ignore_base_python_conflict, ignore_basepython_conflict
    :default: True
@@ -218,8 +219,8 @@ Python
 tox environment
 ---------------
 
-Base
-~~~~
+Base options
+~~~~~~~~~~~~
 
 .. conf::
    :keys: envname, env_name
@@ -466,8 +467,8 @@ Package
    Indicates where the packaging root file exists (historically setup.py file or pyproject.toml now).
 
 
-Python
-~~~~~~
+Python options
+~~~~~~~~~~~~~~
 .. conf::
    :keys: base_python, basepython
    :default: {package_root}

docs/development.rst

@@ -223,3 +223,15 @@ initiate a vote among the existing maintainers.
     - PyPI Publishing Access
     - CI Administration capabilities
     - ReadTheDocs Administration capabilities
+    - The list below
+
+.. _current-maintainers:
+
+Current maintainers
+^^^^^^^^^^^^^^^^^^^
+
+-  `Anthony Sottile <https://github.com/asottile>`_
+-  `Bernát Gábor <https://github.com/gaborbernat>`_
+-  `Jürgen Gmach <https://github.com/jugmac00>`_
+-  `Miroslav Šedivý <https://github.com/eumiro>`_
+-  `Oliver Bestwalter <https://github.com/obestwalter>`_

docs/img/overview.mermaidjs

@@ -0,0 +1,40 @@
+stateDiagram-v2
+%%{init:{'state':{'nodeSpacing': 0, 'rankSpacing': 20}}}%%
+
+[*] --> conf
+conf --> tox_env
+
+state tox_env {
+    state hdi <<choice>>
+    state hpi <<choice>>
+    state fpi <<choice>>
+
+    [*] --> create
+    create --> hdi : has (new) project dependencies (deps)
+    hdi --> deps: yes
+    hdi --> hpi: no, has package
+    deps --> hpi: has package
+    hpi --> fpi: yes, built package in this run
+    hpi --> commands : no
+    fpi --> install_deps: yes
+    fpi --> package: no
+    package --> install_deps
+    install_deps --> install
+    install --> commands
+    commands --> commands: for each entry <br>in commands*
+    commands --> [*] : pass outcome to report
+}
+tox_env --> tox_env :for each tox environment
+
+tox_env --> report
+report --> report :for each tox environment
+report --> [*]
+
+conf: build configuration (CLI + files) <br> identify environments to run
+create: create an isolated tox environment <br> the other steps executed within this
+deps: install project dependencies (if has deps)
+package: build package
+install: install package without dependencies
+install_deps: install (new) package dependencies
+commands: run command
+report: report the outcome of the run