docs: rework CI a bit, more modern skipping (pybind#3424)

* docs: rework CI a bit, more modern skipping

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.github/workflows/ci.yml

@@ -704,14 +704,11 @@ jobs:
     - name: Install Doxygen
       run: sudo apt-get install -y doxygen librsvg2-bin # Changed to rsvg-convert in 20.04
 
-    - name: Install docs & setup requirements
-      run: python3 -m pip install -r docs/requirements.txt
-
     - name: Build docs
-      run: python3 -m sphinx -W -b html docs docs/.build
+      run: pipx run nox -s docs
 
     - name: Make SDist
-      run: python3 setup.py sdist
+      run: pipx run nox -s build -- --sdist
 
     - run: git status --ignored
 
@@ -723,7 +720,7 @@ jobs:
     - name: Compare Dists (headers only)
       working-directory: include
       run: |
-        python3 -m pip install --user -U ../dist/*
+        python3 -m pip install --user -U ../dist/*.tar.gz
         installed=$(python3 -c "import pybind11; print(pybind11.get_include() + '/pybind11')")
         diff -rq $installed ./pybind11
 

docs/Doxyfile

@@ -18,6 +18,5 @@ ALIASES               += "endrst=\endverbatim"
 QUIET                  = YES
 WARNINGS               = YES
 WARN_IF_UNDOCUMENTED   = NO
-PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS \
-                         PY_MAJOR_VERSION=3 \
+PREDEFINED             = PY_MAJOR_VERSION=3 \
                          PYBIND11_NOINLINE

docs/requirements.txt

@@ -1,8 +1,5 @@
-breathe==4.26.1
-# docutils 0.17 breaks HTML tags & RTD theme
-# https://github.com/sphinx-doc/sphinx/issues/9001
-docutils==0.16
-sphinx==3.3.1
-sphinx_rtd_theme==0.5.0
-sphinxcontrib-moderncmakedomain==3.17
-sphinxcontrib-svg2pdfconverter==1.1.0
+breathe==4.31.0
+sphinx==3.5.4
+sphinx_rtd_theme==1.0.0
+sphinxcontrib-moderncmakedomain==3.19
+sphinxcontrib-svg2pdfconverter==1.1.1

include/pybind11/pytypes.h

@@ -287,10 +287,10 @@ class object : public handle {
     struct borrowed_t { };
     struct stolen_t { };
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS  // Issue in breathe 4.26.1
+    /// @cond BROKEN
     template <typename T> friend T reinterpret_borrow(handle);
     template <typename T> friend T reinterpret_steal(handle);
-#endif
+    /// @endcond
 
 public:
     // Only accessible from derived classes and the reinterpret_* functions
@@ -1717,7 +1717,7 @@ class memoryview : public object {
 #endif
 };
 
-#ifndef DOXYGEN_SHOULD_SKIP_THIS
+/// @cond DUPLICATE
 inline memoryview memoryview::from_buffer(
     void *ptr, ssize_t itemsize, const char* format,
     detail::any_container<ssize_t> shape,
@@ -1745,7 +1745,7 @@ inline memoryview memoryview::from_buffer(
         throw error_already_set();
     return memoryview(object(obj, stolen_t{}));
 }
-#endif  // DOXYGEN_SHOULD_SKIP_THIS
+/// @endcond
 /// @} pytypes
 
 /// \addtogroup python_builtins

noxfile.py

@@ -57,10 +57,10 @@ def docs(session: nox.Session) -> None:
     session.chdir("docs")
 
     if "pdf" in session.posargs:
-        session.run("sphinx-build", "-M", "latexpdf", ".", "_build")
+        session.run("sphinx-build", "-b", "latexpdf", ".", "_build")
         return
 
-    session.run("sphinx-build", "-M", "html", ".", "_build")
+    session.run("sphinx-build", "-b", "html", ".", "_build")
 
     if "serve" in session.posargs:
         session.log("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")
@@ -86,6 +86,8 @@ def build(session: nox.Session) -> None:
 
     session.install("build")
     session.log("Building normal files")
-    session.run("python", "-m", "build")
+    session.run("python", "-m", "build", *session.posargs)
     session.log("Building pybind11-global files (PYBIND11_GLOBAL_SDIST=1)")
-    session.run("python", "-m", "build", env={"PYBIND11_GLOBAL_SDIST": "1"})
+    session.run(
+        "python", "-m", "build", *session.posargs, env={"PYBIND11_GLOBAL_SDIST": "1"}
+    )