docs: use Furo (#3109)

* docs: try using Furo

* docs: darker output

* docs: improve logo for dark background

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

Author: henryiii

docs/_static/css/custom.css

@@ -0,0 +1,3 @@
+.highlight .go {
+  color: #707070;
+}

docs/_static/theme_overrides.css

@@ -35,6 +35,7 @@
 # ones.
 extensions = [
     "breathe",
+    "sphinx_copybutton",
     "sphinxcontrib.rsvgconverter",
     "sphinxcontrib.moderncmakedomain",
 ]
@@ -125,23 +126,7 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 
-on_rtd = os.environ.get("READTHEDOCS", None) == "True"
-
-if not on_rtd:  # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-
-    html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
-    html_context = {"css_files": ["_static/theme_overrides.css"]}
-else:
-    html_context = {
-        "css_files": [
-            "//media.readthedocs.org/css/sphinx_rtd_theme.css",
-            "//media.readthedocs.org/css/readthedocs-doc-embed.css",
-            "_static/theme_overrides.css",
-        ]
-    }
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -172,6 +157,10 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
+html_css_files = [
+    "css/custom.css",
+]
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.

docs/conf.py

@@ -1,5 +1,6 @@
-breathe==4.32.0
-sphinx==4.4.0
-sphinx_rtd_theme==1.0.0
+breathe==4.34.0
+furo==2022.6.21
+sphinx==5.0.2
+sphinx-copybutton==0.5.0
 sphinxcontrib-moderncmakedomain==3.21.4
 sphinxcontrib-svg2pdfconverter==1.2.0

docs/pybind11-logo.png

@@ -61,10 +61,10 @@ def docs(session: nox.Session) -> None:
     session.chdir("docs")
 
     if "pdf" in session.posargs:
-        session.run("sphinx-build", "-b", "latexpdf", ".", "_build")
+        session.run("sphinx-build", "-M", "latexpdf", ".", "_build")
         return
 
-    session.run("sphinx-build", "-b", "html", ".", "_build")
+    session.run("sphinx-build", "-M", "html", ".", "_build")
 
     if "serve" in session.posargs:
         session.log("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")