docs: update and clean up warnings (scikit-build#979)

* docs: update and clean up warnings Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com> * Update README.rst --------- Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
holzschu · May 17, 2023 · 2ba690d · 2ba690d
1 parent f2d253e
commit 2ba690d
Show file tree

Hide file tree

Showing 10 changed files with 61 additions and 72 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -10,9 +10,9 @@ formats: all
 
 # Set the version of Python
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.11"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

diff --git a/CHANGES.rst b/CHANGES.rst
@@ -26,8 +26,8 @@ build. NetBSD was reported to work, so was added to the BSD's supported.
 Bug fixes
 ---------
 
-* Generator args were missing for actual compile in #975
-* Add support for netbsd & pyodide (future) in #977
+* Generator args were missing for actual compile in :pr:`975`.
+* Add support for netbsd & pyodide (future) in :pr:`977`.
 
 
 
@@ -552,15 +552,15 @@ Bug fixes
 Documentation
 -------------
 
-* Add :doc:`/notes` section to the ``For maintainers`` top-level category that includes a comparison between
+* Add notes section to the ``For maintainers`` top-level category that includes a comparison between
   ``sysconfig`` and ``distutils.sysconfig`` modules.
 
 * Remove obsolete comment in ``cmaker.py``. See :issue:`439`. Thanks :user:`isuruf`
 
 Tests
 -----
 
-* Update :func:`initialize_git_repo_and_commit` to prevent signing message on system with commit signing
+* Update ``initialize_git_repo_and_commit`` to prevent signing message on system with commit signing
   enabled globally.
 
 Scikit-build 0.10.0
@@ -592,7 +592,7 @@ Bug fixes
 Internal API
 ------------
 
-* Add :meth:`skbuild.platforms.windows.find_visual_studio`.
+* Add :func:`skbuild.platform_specifics.windows.find_visual_studio`.
 
 Documentation
 -------------
@@ -964,7 +964,7 @@ Documentation
 
 * Add a command line :ref:`CMake Options <usage_cmake_options>` section to :doc:`Usage <\usage>`.
 
-* Fix :ref:`table <Visual Studio>` listing *Visual Studio IDE* version and
+* Fix :ref:`table <Visual Studio IDE>` listing *Visual Studio IDE* version and
   corresponding with *CPython version* in :doc:`/generators`.
 
 * Improve :doc:`/make_a_release` section.
@@ -988,7 +988,7 @@ Internal API
 * Teach :class:`skbuild.utils.PythonModuleFinder` to search for ``python module``
   in the CMake install tree.
 
-* Update :meth:`skbuild.setuptools_wrap._consolidate` to copy file into the CMake
+* Update :func:`skbuild.setuptools_wrap._consolidate` to copy file into the CMake
   tree only if it exists.
 
 * Update :meth:`skbuild.setuptools_wrap._copy_file` to create directory only if
@@ -1054,7 +1054,7 @@ Documentation
 
 * add :doc:`/generators` section
 
-* add :doc:`/changes` section
+* add :doc:`/history` section
 
 * allow github issues and users to easily be referenced using ``:issue:`XY```
   and ``:user:`username``` markups.
@@ -1173,8 +1173,7 @@ Tests
 
 * Simplify continuous integration
 
- * use `scikit-ci <http://scikit-ci.readthedocs.io/en/latest/>`_ and
-   `scikit-ci-addons`_
+ * use `scikit-ci`_ and `scikit-ci-addons`_
  * speed up build setting up caching
 
 * Makefile:

diff --git a/README.rst b/README.rst
@@ -16,17 +16,25 @@ scikit-build
     :target: https://github.com/orgs/scikit-build/discussions
     :alt: GitHub Discussion
 
-Improved build system generator for CPython C/C++/Fortran/Cython extensions.
+.. START-INTRO
 
-Better support is available for additional compilers, build systems, cross
-compilation, and locating dependencies and determining their build
-requirements.
+**scikit-build** is a Python build system for CPython C/C++/Fortran/Cython
+extensions using CMake.
 
-The **scikit-build** package is fundamentally just glue between
-the ``setuptools`` Python module and `CMake <https://cmake.org/>`_.
+The scikit-build package is fundamentally just glue between the ``setuptools``
+Python module and `CMake`_.
 
-To get started, see `this example <https://scikit-build.readthedocs.io/en/latest/usage.html#example-of-setup-py-cmakelists-txt-and-pyproject-toml>`_ and `scikit-build-sample-projects <https://github.com/scikit-build/scikit-build-sample-projects>`_.
+The next generation of scikit-build, `scikit-build-core`_, is currently under development.
+This provides a simple, reliable build backend for CMake that does not use
+setuptools and provides a lot of new features. Scikit-build-core can also power
+a setuptools-based extension system, which will eventually become the backend
+for scikit-build (classic). If you do not require extensive customization of
+the build process, you should consider trying scikit-build-core instead of
+scikit-build.
 
+To get started, see `this example <https://scikit-build.readthedocs.io/en/latest/usage.html#example-of-setup-py-cmakelists-txt-and-pyproject-toml>`_. For more examples, see `scikit-build-sample-projects <https://github.com/scikit-build/scikit-build-sample-projects>`_.
+
+.. END-INTRO
 
 Latest Release
 --------------
@@ -60,13 +68,14 @@ History
 
 PyCMake was created at SciPy 2014 in response to general difficulties building
 C++ and Fortran based Python extensions across platforms.  It was renamed to
-"scikit-build" in 2016.
+"scikit-build" in 2016. Scikit-build-core was started in 2022.
 
 
 Known Issues
 ------------
 
-These issues are likely to be addressed in upcoming releases.
+These issues are likely to be addressed in upcoming releases, and are
+already addressed in `scikit-build-core`_.
 
 * Editable installs do not work with the latest versions of Setuptools (and had
   issues with older versions, too).
@@ -78,7 +87,6 @@ These issues are likely to be addressed in upcoming releases.
 We are also working on improving scikit-build, so there are some upcoming
 changes and deprecations:
 
-
 * All deprecated setuptools/distutils features are also deprecated in
   scikit-build, like the ``test`` command, ``easy_install``, etc.
 * Older versions of CMake (<3.15) are not recommended; a future version will
@@ -95,6 +103,10 @@ Miscellaneous
 * Documentation: http://scikit-build.readthedocs.org
 * Source code: https://github.com/scikit-build/scikit-build
 * Discussions: https://github.com/orgs/scikit-build/discussions
+* Scikit-build-core: https://github.com/scikit-build/scikit-build-core
 
 
 Support for this work was provided by NSF cooperative agreement `OAC-2209877 <https://www.nsf.gov/awardsearch/showAward?AWD_ID=2209877>`_.
+
+.. _scikit-build-core: https://scikit-build-core.readthedocs.io
+.. _cmake: https://cmake.org
diff --git a/docs/conf.py b/docs/conf.py
@@ -43,7 +43,7 @@
     'sphinxcontrib.moderncmakedomain',
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
-    'sphinx_issues'
+    'sphinx_issues',
 ]
 
 issues_github_path = 'scikit-build/scikit-build'

diff --git a/docs/generators.rst b/docs/generators.rst
@@ -106,7 +106,7 @@ Unix Makefiles
   build system.
 
 
-.. _Visual Studio:
+.. _Visual Studio IDE:
 
 Visual Studio IDE
 ^^^^^^^^^^^^^^^^^

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,33 +1,12 @@
-.. complexity documentation master file, created by
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root ``toctree`` directive.
-
 Welcome to scikit-build
 =======================
 
-**scikit-build** is an improved build system generator for CPython C/C++/Fortran/Cython
-extensions. It provides better support for additional compilers, build
-systems, cross compilation, and locating dependencies and their associated
-build requirements.
-
-The **scikit-build** package is fundamentally just glue between
-the ``setuptools`` Python module and `CMake <https://cmake.org/>`_.
-
-To get started, see :ref:`this example <basic_usage_example>`.
-For more examples, see `scikit-build-sample-projects <https://github.com/scikit-build/scikit-build-sample-projects>`_.
-
-The next generation of scikit-build, `scikit-build-core
-<https://scikit-build-core.readthedocs.io>`_, is currently under development.
-This provides a simple, reliable PEP 517 based build backend for CMake that does
-not use setuptools and provides a lot of new features. Scikit-build-core
-can also power a setuptools-based extension system, which will eventually become
-the backend for scikit-build (classic). If you do not require extensive
-customization of the build process, you should consider trying scikit-build-core
-instead of scikit-build.
+.. include:: ../README.rst
+   :start-after: .. START-INTRO
+   :end-before: .. END-INTRO
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: User guide
 
    installation
@@ -39,9 +18,8 @@ instead of scikit-build.
    authors
    history
 
-
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: For maintainers
 
    make_a_release
@@ -53,10 +31,6 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
-Resources
-=========
 
-* Free software: MIT license
-* Documentation: http://scikit-build.readthedocs.io/en/latest/
-* Source code: https://github.com/scikit-build/scikit-build
-* Discussions: https://github.com/orgs/scikit-build/discussions
+.. include:: ../README.rst
+   :start-after: .. INJECT-CHANGELOG
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -499,7 +499,7 @@ For example, to limit the number of parallel jobs to ``3``, the following could
 Visual Studio IDE
 ^^^^^^^^^^^^^^^^^
 
-If :ref:`Visual Studio` generator is used, there are two types of parallelism:
+If :ref:`Visual Studio IDE` generator is used, there are two types of parallelism:
 
 * target level parallelism
 * object level parallelism

diff --git a/noxfile.py b/noxfile.py
@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import argparse
 import os
+import shutil
 import sys
 from pathlib import Path
 
@@ -63,20 +65,22 @@ def pylint(session):
 @nox.session
 def docs(session):
     """
-    Build the docs.
+    Build the docs. Use "-R" to rebuild faster. Check options with "-- -h".
     """
 
-    session.install(".[docs]")
+    parser = argparse.ArgumentParser(prog=f"{os.path.basename(sys.argv[0])} -s docs")
+    parser.add_argument("--serve", action="store_true", help="Serve the docs")
+    args = parser.parse_args(session.posargs)
+
+    session.install("-e.[docs]")
 
     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")
+    shutil.rmtree("_build")
+    session.run("sphinx-build", "-M", "html", ".", "_build", "-W")
+
+    if args.serve:
+        print("Launching docs at http://localhost:8000/ - use Ctrl-C to quit")
+        session.run("python", "-m", "http.server", "8000", "-d", "_build/html")
 
 
 @nox.session

diff --git a/pyproject.toml b/pyproject.toml
@@ -6,7 +6,6 @@ build-backend = "hatchling.build"
 name = "scikit-build"
 dynamic = ["version", "readme"]
 description = "Improved build system generator for Python C/C++/Fortran/Cython extensions"
-license = "MIT"
 requires-python = ">=3.7"
 authors = [
     { name = "The scikit-build team" },
@@ -82,7 +81,8 @@ content-type = "text/x-rst"
 
 [[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
 path = "README.rst"
-end-before = ".. INJECT-CHANGELOG"
+start-after = ".. START-INTRO"
+end-before = ".. END-INTRO"
 
 [[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
 path = "CHANGES.rst"

diff --git a/skbuild/platform_specifics/abstract.py b/skbuild/platform_specifics/abstract.py
@@ -107,7 +107,7 @@ def get_best_generator(
 
         :param generator_name: If provided, uses only provided generator, \
         instead of trying :attr:`default_generators`.
-        :type generator_name: string or None
+        :type generator_name: str | None
 
         :param skip_generator_test: If set to True and if a generator name is \
         specified, the generator test is skipped. If no generator_name is specified \
@@ -124,7 +124,7 @@ def get_best_generator(
 
         :param cmake_executable: Path to CMake executable used to configure \
         and build the test project used to evaluate if a generator is working.
-        :type cmake_executable: string
+        :type cmake_executable: str
 
         :param cmake_args: List of CMake arguments to use when configuring \
         the test project. Only arguments starting with ``-DCMAKE_`` are \