From 30a96f66e3aeea2be72d517d415f2fb19542485f Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Wed, 14 Feb 2024 12:40:38 -0500 Subject: [PATCH] docs: fix up docs (#454) * docs: fix up docs Signed-off-by: Henry Schreiner * style: pre-commit fixes * chore: clean up a few things Signed-off-by: Henry Schreiner --------- Signed-off-by: Henry Schreiner Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- .github/workflows/build.yml | 4 ++++ .readthedocs.yaml | 16 +++++++++++++ CONTRIBUTING.rst | 2 +- HISTORY.rst | 2 +- README.rst | 12 +++++----- docs/build_system.rst | 10 ++------ docs/building.rst | 2 +- docs/conf.py | 4 ++-- docs/index.rst | 10 ++++---- docs/make.bat | 2 +- docs/make_a_release.rst | 2 +- docs/requirements-docs.txt | 5 ++-- noxfile.py | 48 +++++++++++++++++++++++++++---------- pyproject.toml | 20 +++++++--------- 14 files changed, 87 insertions(+), 52 deletions(-) create mode 100644 .readthedocs.yaml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 151953759..bafa91a39 100644 --- a/.github/workflows/build.yml +++ b/.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/') }} diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..219a9bacb --- /dev/null +++ b/.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 diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 26b71f992..3918d8abc 100644 --- a/CONTRIBUTING.rst +++ b/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 `_ and make sure that the tests pass for all supported Python versions. diff --git a/HISTORY.rst b/HISTORY.rst index 3c3fc15cc..f365f6c72 100644 --- a/HISTORY.rst +++ b/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 `_ and depending on CMake. +`scikit-build `_ and depending on CMake. diff --git a/README.rst b/README.rst index f16fb16bc..7879b8cdb 100644 --- a/README.rst +++ b/README.rst @@ -2,7 +2,7 @@ CMake Python Distributions ========================== -`CMake `_ is used to control the software compilation +`CMake `_ 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,14 +74,14 @@ The last version to provide ``manylinux1`` wheels was ``3.22.x``. Maintainers ----------- -* `How to update CMake version? `_ +* `How to update CMake version? `_ -* `How to make a release? `_ +* `How to make a release? `_ 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 @@ -89,7 +89,7 @@ License ------- This project is maintained by Jean-Christophe Fillion-Robin from Kitware Inc. -It is covered by the `Apache License, Version 2.0 `_. +It is covered by the `Apache License, Version 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 diff --git a/docs/build_system.rst b/docs/build_system.rst index 4a2960a78..33b92724a 100644 --- a/docs/build_system.rst +++ b/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 `_ 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 `_"]; + 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."] diff --git a/docs/building.rst b/docs/building.rst index 410efd6ad..3e3a20aa3 100644 --- a/docs/building.rst +++ b/docs/building.rst @@ -5,7 +5,7 @@ Building the CMake Python wheel Overview -------- -This project has been designed to work with `scikit-build `_. +This project has been designed to work with `scikit-build `_. It provides a `setup.py` and allows to create both source and binary distributions of CMake. diff --git a/docs/conf.py b/docs/conf.py index d201f63d8..677bb35ca 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index f0cb1cf9a..a81884996 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,14 +6,14 @@ Welcome to CMake Python Distributions's documentation! ====================================================== -`CMake `_ is used to control the software compilation +`CMake `_ 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 `_ and `VTK `_. +such as `ITK `_ and `VTK `_. The CMake python wheels provide `CMake 3.28.3 `_. @@ -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 `_. +It is covered by the `Apache License, Version 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 diff --git a/docs/make.bat b/docs/make.bat index 7d1e4b264..0d0b48c79 100644 --- a/docs/make.bat +++ b/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 ) diff --git a/docs/make_a_release.rst b/docs/make_a_release.rst index 1681dca19..eaaff7a55 100644 --- a/docs/make_a_release.rst +++ b/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 diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt index c4bcd5a60..6b52089e9 100644 --- a/docs/requirements-docs.txt +++ b/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+ diff --git a/noxfile.py b/noxfile.py index f62621c87..23c6adacf 100644 --- a/noxfile.py +++ b/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: diff --git a/pyproject.toml b/pyproject.toml index a4c142e09..dd2b71824 100644 --- a/pyproject.toml +++ b/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