Proof-of-concept doc command

.github/workflows/test.yml

@@ -26,6 +26,7 @@ jobs:
         run: |
           pip install -e .
           pip install pytest meson-python ninja
+          pip install -r example_pkg/doc/requirements.txt
       - name: Test
         shell: 'script -q -e -c "bash --noprofile --norc -eo pipefail {0}"'
         env:
@@ -34,3 +35,4 @@ jobs:
           cd example_pkg
           ./dev.py build
           ./dev.py test
+          ./dev.py doc

README.md

@@ -6,7 +6,7 @@ Typically, their lives are made simpler by a Makefile, but Makefiles can be conv
 The rationale behind `devpy` is therefore to provide a simple interface for common development tasks.
 It comes with a few common build commands out the box, but can easily be customized per project.
 
-As a curiosity: the impetus behind developing the tool was the mass migration of scientific Python libraries (SciPy, scikit-image, and NumPy, etc.) to Meson, after distutils was deprecated.
+As a curiosity: the impetus behind developing the tool was the mass migration of scientific Python libraries (SciPy, scikit-image, and NumPy, etc.) to [Meson](https://mesonbuild.com/), after `distutils` was deprecated.
 When many of the build and installation commands changed, it made sense to abstract away the nuisance of having to re-learn them.
 
 ## Configuration

devpy/cmds/__init__.py

@@ -1,3 +1,4 @@
 from ._build import build
 from ._test import test
 from ._shell import ipython, python, shell
+from ._doc import doc

devpy/cmds/_doc.py

@@ -0,0 +1,39 @@
+import sys
+import os
+
+import click
+
+from . import util
+
+
+@click.command()
+@click.option(
+    "--build-dir", default="build", help="Build directory; default is `$PWD/build`"
+)
+@click.option(
+    "--clean", is_flag=True, help="Clean previously built docs before building"
+)
+@click.argument("targets", required=False, nargs=-1)
+def doc(build_dir, targets, clean=False):
+    """📖 Build documentation
+
+    Set the PYTHONPATH to the build path, and invoke `make` in the
+    `doc` directory.
+
+    For a list of Sphinx make targets:
+
+      ./dev.py doc help
+    """
+    if not targets:
+        targets = ["html"]
+    if clean:
+        doc_dir = "./doc/build"
+        if os.path.isdir(doc_dir):
+            print(f"Removing `{doc_dir}`")
+            shutil.rmtree(doc_dir)
+
+    util.set_pythonpath(build_dir)
+
+    print("$ export SPHINXOPTS='-W'")
+    os.environ["SPHINXOPTS"] = "-W"
+    util.run(["make", "-C", "doc"] + list(targets), replace=True)

devpy/cmds/util.py

@@ -45,7 +45,9 @@ def get_site_packages(build_dir):
 def set_pythonpath(build_dir):
     site_packages = get_site_packages(build_dir)
     if site_packages is None:
-        print(f"No `site-packages` directory found under {build_dir}; aborting")
+        print(
+            f"No `site-packages` directory found under {install_dir(build_dir)}; run `./dev.py build` first"
+        )
         sys.exit(1)
 
     env = os.environ

example_pkg/doc/.gitignore

@@ -0,0 +1 @@
+_build

example_pkg/doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

example_pkg/doc/conf.py

@@ -0,0 +1,26 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "devpy"
+copyright = "2022, The Scientific Python developers"
+author = "The Scientific Python developers"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["myst_parser"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "pydata_sphinx_theme"
+html_static_path = ["_static"]

example_pkg/doc/index.md

@@ -0,0 +1,4 @@
+# devpy example package
+
+This example package is used to test `devpy` with.
+It contains one Python extension, namely `example_pkg.echo`.

example_pkg/doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

example_pkg/doc/requirements.txt

@@ -0,0 +1,3 @@
+sphinx
+myst-parser
+pydata-sphinx-theme

example_pkg/pyproject.toml

@@ -14,4 +14,5 @@ package = 'example_pkg'
 
 "Build" = ["devpy.build", "devpy.test"]
 "Environments" = ["devpy.shell", "devpy.ipython", "devpy.python"]
+"Documentation" = ["devpy.doc"]
 "Extensions" = [".devpy/cmds.py:example"]

pyproject.toml

@@ -25,20 +25,3 @@ homepage = "https://github.com/scientific-python/devpy"
 
 [tool.setuptools.packages.find]
 include = ["devpy*"]
-
-[tool.pytest.ini_options]
-filterwarnings = [
-  "ignore:cannot collect 'test' because it is not a function:",
-]
-
-[tool.devpy]
-package = 'devpy'
-
-[tool.devpy.commands]
-# If you don't need sections, you can also provide a list of commands under [tool.devpy]:
-#
-# commands = ["devpy.build", "devpy.test", "devpy.shell", "devpy.ipython", "devpy.python", "custom/cmds.py:example"]
-
-"Build" = ["devpy.build", "devpy.test"]
-"Environments" = ["devpy.shell", "devpy.ipython", "devpy.python"]
-"Extensions" = ["example_pkg/.devpy/cmds.py:example"]