docs: fix up docs (#454)

* docs: fix up docs

Signed-off-by: Henry Schreiner <[email protected]>

* style: pre-commit fixes

* chore: clean up a few things

Signed-off-by: Henry Schreiner <[email protected]>

---------

Signed-off-by: Henry Schreiner <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: henryiii

.github/workflows/build.yml

@@ -17,6 +17,10 @@ on:
     tags:
       - "*.*.*"
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 env:
   USE_QEMU: ${{ fromJSON(github.event.inputs.use_qemu || 'false') || (github.event_name == 'schedule') || startsWith(github.ref, 'refs/tags/') }}
 

.readthedocs.yaml

@@ -0,0 +1,16 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+sphinx:
+   configuration: docs/conf.py
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - requirements: docs/requirements-docs.txt

CONTRIBUTING.rst

@@ -103,7 +103,7 @@ Before you submit a pull request, check that it meets these guidelines:
    feature to the list in `README.rst`.
 
 3. The pull request should work for Python 2.7, and 3.6+.
-   Check `GitHub Actions https://github.com/scikit-build/cmake-python-distributions/actions/workflows/build.yml`_
+   Check `GitHub Actions <https://github.com/scikit-build/cmake-python-distributions/actions/workflows/build.yml>`_
    and make sure that the tests pass for all supported Python versions.
 
 

HISTORY.rst

@@ -5,4 +5,4 @@ History
 
 cmake-python-distributions was initially developed in September 2016 by
 Jean-Christophe Fillion-Robin to facilitate the distribution of project using
-`scikit-build <http://scikit-build.readthedocs.io/>`_ and depending on CMake.
+`scikit-build <https://scikit-build.readthedocs.io/>`_ and depending on CMake.

README.rst

@@ -2,7 +2,7 @@
 CMake Python Distributions
 ==========================
 
-`CMake <http://www.cmake.org>`_ is used to control the software compilation
+`CMake <https://cmake.org>`_ is used to control the software compilation
 process using simple platform and compiler independent configuration files,
 and generate native makefiles and workspaces that can be used in the
 compiler environment of your choice.
@@ -74,22 +74,22 @@ The last version to provide ``manylinux1`` wheels was ``3.22.x``.
 Maintainers
 -----------
 
-* `How to update CMake version? <http://cmake-python-distributions.readthedocs.io/en/latest/update_cmake_version.html>`_
+* `How to update CMake version? <https://cmake-python-distributions.readthedocs.io/en/latest/update_cmake_version.html>`_
 
-* `How to make a release? <http://cmake-python-distributions.readthedocs.io/en/latest/make_a_release.html>`_
+* `How to make a release? <https://cmake-python-distributions.readthedocs.io/en/latest/make_a_release.html>`_
 
 Miscellaneous
 -------------
 
-* Documentation: http://cmake-python-distributions.readthedocs.io/en/latest/
+* Documentation: https://cmake-python-distributions.readthedocs.io/en/latest/
 * Source code: https://github.com/scikit-build/cmake-python-distributions
 * Mailing list: https://groups.google.com/forum/#!forum/scikit-build
 
 License
 -------
 
 This project is maintained by Jean-Christophe Fillion-Robin from Kitware Inc.
-It is covered by the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.
+It is covered by the `Apache License, Version 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`_.
 
 CMake is distributed under the OSI-approved BSD 3-clause License.
-For more information about CMake, visit http://cmake.org
+For more information about CMake, visit https://cmake.org

docs/build_system.rst

@@ -2,12 +2,8 @@
 Understanding the Build-system
 ==============================
 
-CMakeLists.txt
---------------
 
-.. _CMakeLists: https://github.com/scikit-build/cmake-python-distributions/blob/master/CMakeLists.txt
-
-The build system is described by the `CMakeLists.txt <CMakeLists>`_ and is composed of few projects each responsible
+The build system is described by the ``CMakeLists.txt`` and is composed of few projects each responsible
 for a specific task. Once configured, the `Outer Project` is responsible for driving the overall build
 composed of multiple project called `external project`. Here is the list of `external project`:
 
@@ -16,8 +12,6 @@ composed of multiple project called `external project`. Here is the list of `ext
 * ``CMakeProject-build``
 * ``CMakePythonDistributions``: This corresponds to the `Inner Project` represented below.
 
-.. _ ..CMakeLists\.txt: https://github.com/scikit-build/cmake-python-distributions/blob/master/CMakeLists.txt
-
 The flow chart represented below illustrates which external projects are included based on the configure
 options and describes the role of each one:
 
@@ -36,7 +30,7 @@ options and describes the role of each one:
             color = "#FFF0D7";
 
             // properties
-            configure [shape = beginpoint, label = "CMakeLists", description="See `CMakeLists.txt <CMakeLists>`_"];
+            configure [shape = beginpoint, label = "CMakeLists", description="CMake configuration file"];
             ask_download [label ="Download source ?", shape = diamond, description = "If option ``CMakeProject_SOURCE_DIR`` is set, skip source download."];
             download_source [label ="Download Source archive", description = "External project downloading archives from https://cmake.org/files/."]
             reuse_source_dir [label ="Re-use source directory", description = "Empty external project."]

docs/building.rst

@@ -5,7 +5,7 @@ Building the CMake Python wheel
 Overview
 --------
 
-This project has been designed to work with `scikit-build <http://scikit-build.readthedocs.io/>`_.
+This project has been designed to work with `scikit-build <https://scikit-build.readthedocs.io/>`_.
 
 It provides a `setup.py` and allows to create both source and binary distributions of
 CMake.

docs/conf.py

@@ -73,7 +73,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -160,7 +160,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/index.rst

@@ -6,14 +6,14 @@
 Welcome to CMake Python Distributions's documentation!
 ======================================================
 
-`CMake <http://www.cmake.org>`_ is used to control the software compilation
+`CMake <https://cmake.org>`_ is used to control the software compilation
 process using simple platform and compiler independent configuration files,
 and generate native makefiles and workspaces that can be used in the
 compiler environment of your choice.
 
 The suite of CMake tools were created by Kitware in response to the need
 for a powerful, cross-platform build environment for open-source projects
-such as `ITK <https://www.itk.org>`_ and `VTK <http://www.vtk.org>`_.
+such as `ITK <https://itk.org>`_ and `VTK <https://vtk.org>`_.
 
 The CMake python wheels provide `CMake 3.28.3 <https://cmake.org/cmake/help/v3.28/index.html>`_.
 
@@ -49,11 +49,11 @@ Resources
 =========
 
 This project is maintained by Jean-Christophe Fillion-Robin from Kitware Inc.
-It is covered by the `Apache License, Version 2.0 <http://www.apache.org/licenses/LICENSE-2.0>`_.
+It is covered by the `Apache License, Version 2.0 <https://www.apache.org/licenses/LICENSE-2.0>`_.
 
 CMake is distributed under the OSI-approved BSD 3-clause License.
-For more information about CMake, visit http://cmake.org
+For more information about CMake, visit https://cmake.org
 
-* Documentation: http://cmake-python-distributions.readthedocs.io/en/latest/
+* Documentation: https://cmake-python-distributions.readthedocs.io/en/latest/
 * Source code: https://github.com/scikit-build/cmake-python-distributions
 * Mailing list: https://groups.google.com/forum/#!forum/scikit-build

docs/make.bat

@@ -67,7 +67,7 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.https://sphinx-doc.org/
 	exit /b 1
 )
 

docs/make_a_release.rst

@@ -122,7 +122,7 @@ means that ``echo "Hello"`` should be copied and evaluated in the terminal.
 
 
 .. _virtualenvwrapper: https://virtualenvwrapper.readthedocs.io/
-.. _virtualenv: http://virtualenv.readthedocs.io
+.. _virtualenv: https://virtualenv.pypa.io/en/latest
 .. _venv: https://docs.python.org/3/library/venv.html
 
 

docs/requirements-docs.txt

@@ -1,7 +1,8 @@
 docutils
-funcparserlib>=1.0.0a0
+funcparserlib>=1.0.0
+pillow<10
 pygments
 scikit-build
 sphinx
 sphinx_rtd_theme
-sphinxcontrib-blockdiag
+sphinxcontrib-blockdiag # old, not compatible with pillow 10+

noxfile.py

@@ -55,25 +55,49 @@ def tests(session: nox.Session) -> str:
     session.run("pytest", *session.posargs)
 
 
-@nox.session
-def docs(session: nox.Session) -> str:
+@nox.session(reuse_venv=True)
+def docs(session: nox.Session) -> None:
     """
-    Build the docs.
+    Build the docs. Pass "--serve" to serve. Pass "-b linkcheck" to check links.
     """
 
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--serve", action="store_true", help="Serve after building")
+    parser.add_argument(
+        "-b", dest="builder", default="html", help="Build target (default: html)"
+    )
+    args, posargs = parser.parse_known_args(session.posargs)
+
+    if args.builder != "html" and args.serve:
+        session.error("Must not specify non-HTML builder with --serve")
+
+    extra_installs = ["sphinx-autobuild"] if args.serve else []
+
     wheel = build(session)
-    session.install("-r", "requirements-docs.txt")
+    session.install("-r", "docs/requirements-docs.txt", *extra_installs)
     session.install(f"./dist/{wheel}")
 
     session.chdir("docs")
-    session.run("sphinx-build", "-M", "html", ".", "_build")
-
-    if session.posargs:
-        if "serve" in session.posargs:
-            print("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")
-            session.run("python", "-m", "http.server", "8000", "-d", "_build/html")
-        else:
-            print("Unsupported argument to docs")
+
+    if args.builder == "linkcheck":
+        session.run(
+            "sphinx-build", "-b", "linkcheck", ".", "_build/linkcheck", *posargs
+        )
+        return
+
+    shared_args = (
+        "-n",  # nitpicky mode
+        "-T",  # full tracebacks
+        f"-b={args.builder}",
+        ".",
+        f"_build/{args.builder}",
+        *posargs,
+    )
+
+    if args.serve:
+        session.run("sphinx-autobuild", *shared_args)
+    else:
+        session.run("sphinx-build", "--keep-going", *shared_args)
 
 
 def _bump(session: nox.Session, name: str, repository: str, branch: str, script: str, files) -> None:

pyproject.toml

@@ -21,7 +21,7 @@ before-build = "pip install -r requirements-repair.txt"
 repair-wheel-command = "python scripts/repair_wheel.py -w {dest_dir} {wheel}"
 test-extras = "test"
 test-command = "pytest {project}/tests"
-build-verbosity = "1"
+build-verbosity = 1
 
 [tool.cibuildwheel.linux]
 before-all = [
@@ -55,8 +55,10 @@ MACOSX_DEPLOYMENT_TARGET = "10.10"
 
 
 [tool.ruff]
-select = [
-  "E", "F", "W", # flake8
+src = ["src"]
+
+[tool.ruff.lint]
+extend-select = [
   "B",           # flake8-bugbear
   "I",           # isort
   "ARG",         # flake8-unused-arguments
@@ -75,22 +77,16 @@ select = [
   "NPY",         # NumPy specific rules
   "PD",          # pandas-vet
 ]
-extend-ignore = [
-  "PLR",    # Design related pylint codes
-  "E501",   # Line too long
+ignore = [
+  "PLR09",  # Too many X
   "RUF005", # Python 3 needed
   "B904",   # Python 3 needed
   "SIM105", # Python 3 needed
 ]
-src = ["src"]
-unfixable = [
-  "T20",  # Removes print statements
-  "F841", # Removes unused variables
-]
 exclude = ["src/cmake/_version.py"]
 flake8-unused-arguments.ignore-variadic-names = true
 
-[tool.ruff.per-file-ignores]
+[tool.ruff.lint.per-file-ignores]
 "docs/conf.py" = ["E402"]
 "*.pyi" = ["ARG001"]
 "noxfile.py" = ["PLW0603"] # Could be fixed if Python 2 dropped