Start plugin interface documentation, add installer

.gitignore

@@ -15,4 +15,4 @@ dist
 /docs/_draft.rst
 pip-wheel-metadata
 Dockerfile
-/tox_.py
+/toxfile.py

.pre-commit-config.yaml

@@ -12,15 +12,15 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/asottile/pyupgrade
-    rev: v2.10.0
+    rev: v2.11.0
     hooks:
       - id: pyupgrade
         args: ["--py36-plus"]
         exclude: "^(src/tox/util/pep517/backend.py|tests/demo_pkg_inline/build.py)$"
       - id: pyupgrade
         files: "^(src/tox/util/pep517/backend.py|tests/demo_pkg_inline/build.py)$"
   - repo: https://github.com/PyCQA/isort
-    rev: 5.7.0
+    rev: 5.8.0
     hooks:
       - id: isort
   - repo: https://github.com/psf/black
@@ -30,7 +30,7 @@ repos:
         args:
           - --safe
   - repo: https://github.com/asottile/setup-cfg-fmt
-    rev: v1.16.0
+    rev: v1.17.0
     hooks:
       - id: setup-cfg-fmt
         args:

docs/_static/custom.css

@@ -3,63 +3,19 @@
   max-width: 100%;
 }
 
-#virtualenv img {
-  margin-bottom: 6px;
-}
-
-/* Allow table content to wrap around */
-.wy-table-responsive table th,
-.wy-table-responsive table td {
-  /* !important because RTD has conflicting stylesheets */
-  white-space: normal !important;
-  padding: 8px 6px !important;
-}
-
-.wy-table-responsive table {
-  width: 100%;
-  margin-left: 0 !important;
-}
-
-.rst-content table.docutils td ol {
-  margin-bottom: 0;
-}
-
-.rst-content table.docutils td ul {
-  margin-bottom: 0;
-}
-
-.rst-content table.docutils td p {
-  margin-bottom: 0;
-}
-
-div[class*="highlight-"] {
-  margin-bottom: 12px;
-}
-
-/* Tweak whitespace on the release history page */
-#release-history p {
-  margin-bottom: 0;
-  margin-top: 0;
-}
-
-#release-history h3 {
-  margin-bottom: 6px;
-}
-
-#release-history ul {
-  margin-bottom: 12px;
+/* Reduce whitespace on the inline-code snippets and add softer corners */
+.rst-content code {
+  padding: 2px 3px;
+  border-radius: 3px;
 }
 
-#release-history ul ul {
-  margin-bottom: 0;
+dl {
+  margin-bottom: 0!important;
 }
 
-#release-history h2 {
-  margin-bottom: 12px;
+dd {
+  margin-bottom: 2px!important;
 }
-
-/* Reduce whitespace on the inline-code snippets and add softer corners */
-.rst-content code {
-  padding: 2px 3px;
-  border-radius: 3px;
+.rst-content dd p {
+  margin-bottom: 0px;
 }

docs/changelog.rst

@@ -1,6 +1,5 @@
 Release History
 ===============
-
 .. include:: _draft.rst
 
 .. towncrier release notes start

docs/changelog/1926.bugfix.rst

@@ -1,2 +1 @@
- Environments with a platform mismatch are no longer silently skipped,
- but properly reported - by :user:`jugmac00`.
+Environments with a platform mismatch are no longer silently skipped, but properly reported - by :user:`jugmac00`.

docs/changelog/1991.bugfix.rst

@@ -0,0 +1,2 @@
+Requirements and constraints files handling got reimplemented, which should fix all open issues related to this area
+- by :user:`gaborbernat`.

docs/changelog/1991.doc.rst

@@ -0,0 +1,4 @@
+Start documenting the plugin interface. Added :meth:`tox_register_tox_env <tox.plugin.spec.tox_register_tox_env>`,
+:meth:`tox_add_option <tox.plugin.spec.tox_add_option>`,
+:meth:`tox_add_core_config <tox.plugin.spec.tox_add_core_config>`,
+:meth:`tox_configure <tox.plugin.spec.tox_configure>` - by :user:`gaborbernat`.

docs/changelog/1991.feature.rst

@@ -0,0 +1,2 @@
+Introduce the installer concept, and collect pip installation into a ``pip`` package, also attach to this
+the requirements file parsing which got a major rework - by :user:`gaborbernat`.

docs/conf.py

@@ -1,9 +1,16 @@
-import subprocess
 import sys
 from datetime import date, datetime
 from pathlib import Path
+from subprocess import check_output
+from typing import Any, Optional, Tuple, Union
 
 import sphinx_rtd_theme
+from docutils.nodes import Element
+from sphinx.addnodes import pending_xref
+from sphinx.application import Sphinx
+from sphinx.builders import Builder
+from sphinx.environment import BuildEnvironment
+from sphinx.ext.autodoc import Options
 
 from tox.version import __version__
 
@@ -17,7 +24,11 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
     "sphinx_argparse_cli",
+    "sphinx_autodoc_typehints",
+    "sphinx_inline_tabs",
+    "sphinx_copybutton",
 ]
 
 templates_path = []
@@ -27,7 +38,7 @@
 
 master_doc = "index"
 pygments_style = "default"
-always_document_param_types = True
+
 project = name
 today_fmt = "%B %d, %Y"
 
@@ -48,8 +59,17 @@
 html_logo = "_static/img/tox.svg"
 html_favicon = "_static/img/toxfavi.ico"
 htmlhelp_basename = "Pastedoc"
-autoclass_content = "both"  # Include __init__ in class documentation
+
+autoclass_content = "class"
 autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "member-order": "bysource",
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+autodoc_typehints = "none"
+always_document_param_types = False
+typehints_fully_qualified = True
 autosectionlabel_prefix_document = True
 
 extlinks = {
@@ -58,24 +78,61 @@
     "user": ("https://github.com/%s", "@"),
     "pypi": ("https://pypi.org/project/%s", ""),
 }
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "packaging": ("https://packaging.pypa.io/en/latest", None),
+}
+nitpicky = True
+nitpick_ignore = []
+
 
+def skip_member(app: Sphinx, what: str, name: str, obj: Any, would_skip: bool, options: Options) -> bool:  # noqa: U100
+    return True if name in options.get("exclude-members", set()) else would_skip
 
-def generate_draft_news():
+
+def process_signature(
+    app: Sphinx, objtype: str, name: str, obj: Any, options: Options, args: str, retann: Optional[str]  # noqa: U100
+) -> Union[None, Tuple[None, None]]:
+    # skip-member is not checked for class level docs, so disable via signature processing
+    return (None, None) if objtype == "class" and "__init__" in options.get("exclude-members", set()) else None
+
+
+def setup(app: Sphinx) -> None:
     root = Path(__file__).parents[1]
     exe = Path(sys.executable)
     towncrier = exe.with_name(f"towncrier{exe.suffix}")
-    new = subprocess.check_output([str(towncrier), "--draft", "--version", "NEXT"], cwd=root, universal_newlines=True)
+    new = check_output([str(towncrier), "--draft", "--version", "NEXT"], cwd=root, universal_newlines=True)
     (root / "docs" / "_draft.rst").write_text("" if "No significant changes" in new else new)
 
+    from sphinx.domains.python import PythonDomain
 
-generate_draft_news()
+    class PatchedPythonDomain(PythonDomain):
+        def resolve_xref(
+            self,
+            env: BuildEnvironment,
+            fromdocname: str,
+            builder: Builder,
+            type: str,
+            target: str,
+            node: pending_xref,
+            contnode: Element,
+        ) -> Element:
+            # fixup some wrongly resolved mappings
+            mapping = {
+                "_io.TextIOWrapper": "io.TextIOWrapper",
+                "Future": "concurrent.futures.Future",
+                "_F": "typing.TypeVar",
+                "V": "typing.TypeVar",
+                "T": "typing.TypeVar",
+                "tox.config.of_type.T": "typing.TypeVar",
+                "tox.config.loader.api.T": "typing.TypeVar",
+                "tox.config.loader.convert.T": "typing.TypeVar",
+            }
+            if target in mapping:
+                node["reftarget"] = mapping[target]
+            return super().resolve_xref(env, fromdocname, builder, type, target, node, contnode)
 
-
-def setup(app):
+    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")
-
-    # the CLI arguments are dynamically generated - do not cache
-    doc_tree = Path(app.doctreedir)
-    cli_interface_doctree = doc_tree / "cli_interface.doctree"
-    if cli_interface_doctree.exists():
-        cli_interface_doctree.unlink()

docs/index.rst

@@ -70,6 +70,6 @@ you want to do more research, we recommend taking a look at these projects:
    installation
    user_guide
    cli_interface
-   extend
+   plugins
    development
    changelog