Use furo docs theme (#2496)

Author: gaborbernat

docs/changelog/2481.bugfix.rst

@@ -1 +1 @@
-Fix broken prompt in Nushell when activating virtual environment.
+Fix broken prompt in Nushell when activating virtual environment - by :user:`kubouc`.

docs/changelog/2496.docs.rst

@@ -0,0 +1 @@
+Use ``furo`` theme - by :user:`gaborbernat`.

docs/conf.py

@@ -3,8 +3,6 @@
 from datetime import date, datetime
 from pathlib import Path
 
-import sphinx_rtd_theme
-
 from virtualenv.version import __version__
 
 company = "PyPA"
@@ -30,21 +28,11 @@
 project = name
 today_fmt = "%B %d, %Y"
 
-html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-html_theme_options = {
-    "canonical_url": "https://virtualenv.pypa.io/",
-    "logo_only": False,
-    "display_version": True,
-    "prev_next_buttons_location": "bottom",
-    "collapse_navigation": False,
-    "sticky_navigation": True,
-    "navigation_depth": 6,
-    "includehidden": True,
-}
-html_static_path = ["_static"]
-html_last_updated_fmt = datetime.now().isoformat()
-htmlhelp_basename = "Pastedoc"
+html_theme = "furo"
+html_title, html_last_updated_fmt = "tox", datetime.now().isoformat()
+pygments_style, pygments_dark_style = "sphinx", "monokai"
+html_static_path, html_css_files = ["_static"], ["custom.css"]
+
 autoclass_content = "both"  # Include __init__ in class documentation
 autodoc_member_order = "bysource"
 autosectionlabel_prefix_document = True
@@ -57,21 +45,14 @@
 }
 
 
-def generate_draft_news():
-    root = Path(__file__).parents[1]
-    new = subprocess.check_output(
-        [sys.executable, "-m", "towncrier", "--draft", "--version", "NEXT"],
-        cwd=root,
-        text=True,
-    )
-    dest = root / "docs" / "_draft.rst"
-    dest.write_text("" if "No significant changes" in new else new)
-
-
-generate_draft_news()
-
-
 def setup(app):
+    here = Path(__file__).parent
+    root, exe = here.parent, Path(sys.executable)
+    towncrier = exe.with_name(f"towncrier{exe.suffix}")
+    cmd = [str(towncrier), "build", "--draft", "--version", "NEXT"]
+    new = subprocess.check_output(cmd, cwd=root, text=True, stderr=subprocess.DEVNULL)
+    (root / "docs" / "_draft.rst").write_text("" if "No significant changes" in new else new)
+
     # the CLI arguments are dynamically generated
     doc_tree = Path(app.doctreedir)
     cli_interface_doctree = doc_tree / "cli_interface.doctree"

pyproject.toml

@@ -42,10 +42,11 @@ dependencies = [
   "platformdirs<3,>=2.4",
 ]
 optional-dependencies.docs = [
+  "furo>=2022.12.7",
   "proselint>=0.13",
-  "sphinx>=5.3",
+  "sphinx>=6.1.3",
   "sphinx-argparse>=0.4",
-  "sphinx-rtd-theme>=1.1.1",
+  "sphinxcontrib-towncrier>=0.2.1a0",
   "towncrier>=22.12",
 ]
 optional-dependencies.test = [
@@ -147,3 +148,11 @@ markers = ["slow"]
 timeout = 600
 addopts = "--tb=auto -ra --showlocals --no-success-flaky-report"
 env = ["PYTHONIOENCODING=utf-8"]
+
+[tool.towncrier]
+name = "tox"
+filename = "docs/changelog.rst"
+directory = "docs/changelog"
+title_format = false
+issue_format = ":issue:`{issue}`"
+template = "docs/changelog/template.jinja2"

tox.ini

@@ -60,7 +60,6 @@ description = build documentation
 extras =
     docs
 commands =
-    python -c 'import glob; import subprocess; subprocess.call(["proselint"] + glob.glob("docs/*.rst") + glob.glob("docs/**/*.rst"))'
     sphinx-build -d "{envtmpdir}/doctree" docs "{toxworkdir}/docs_out" --color -b html {posargs:-W}
     python -c 'import pathlib; print("documentation available under file://\{0\}".format(pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html"))'
 

whitelist.txt

@@ -51,6 +51,7 @@ cust
 defpath
 delenv
 deque
+devnull
 distlib
 distro
 dll
@@ -88,7 +89,6 @@ gevent
 groupby
 hgignore
 hkey
-htmlhelp
 img
 impls
 iread
@@ -181,7 +181,6 @@ rglob
 rmdir
 rpartition
 rst
-rtd
 scr
 sdist
 setenv
@@ -210,6 +209,7 @@ testpth
 tgroup
 tk
 topdown
+towncrier
 tox
 truediv
 unsecure