doc/: start generating API documentation from docstrings

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

15 files changed, 76 insertions, 22 deletions

diff --git a/doc/GNUmakefile b/doc/GNUmakefile
new file mode 100644
index 0000000..53d9b35
--- /dev/null
+++ b/doc/GNUmakefile
@@ -0,0 +1,28 @@
+include ../consfigurator.mk
+
+LISP = $(wildcard ../src/property/*.lisp ../src/util/*.lisp) \
+	../src/connection.lisp ../src/property.lisp ../src/propspec.lisp \
+	../src/host.lisp ../src/combinator.lisp ../src/deployment.lisp \
+	../src/data.lisp ../src/image.lisp ../src/util.lisp
+PAGES = $(patsubst ../src/%,%,$(LISP:lisp=rst))
+
+.PHONY: all
+all: html info
+
+.PHONY: html info
+html info: $(PAGES) conf.py $(wildcard *.rst */*.rst)
+	sphinx-build -M $@ . _build
+
+$(PAGES) &: $(wildcard *.rst.in */*.rst.in) $(LISP)
+	$(SBCL) --eval "(mapc #'consfigurator::build-manual-rst \
+		              uiop:*command-line-arguments*)" --quit $(PAGES)
+
+.PHONY: clean
+clean:
+	rm -rf _build
+	rm -f $(PAGES)
+
+# property.lisp contains the definition of BUILD-MANUAL-RST.
+.SECONDEXPANSION:
+%.rst: $$(wildcard $$*.rst.in) ../src/$$(*D)/$$(*F).lisp ../src/property.lisp
+	$(SBCL) --eval '(consfigurator::build-manual-rst "$@")' --quit
diff --git a/doc/Makefile b/doc/Makefile
deleted file mode 100644
index 50d9481..0000000
--- a/doc/Makefile
+++ /dev/null
@@ -1,9 +0,0 @@
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
-
-# 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)
diff --git a/doc/combinator.rst.in b/doc/combinator.rst.in
new file mode 100644
index 0000000..d54fcdf
--- /dev/null
+++ b/doc/combinator.rst.in
@@ -0,0 +1,2 @@
+Property combinators
+====================
diff --git a/doc/conf.py b/doc/conf.py
index 984073d..99da27e 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Consfigurator'
-copyright = '2020-2022, Sean Whitton'
+copyright = '2015-2018, 2020-2023, Sean Whitton, 2021-2022 David Bremner'
 author = 'Sean Whitton'
 
 # The full version, including alpha/beta/rc tags
diff --git a/doc/connections.rst b/doc/connection.rst.in
index b958139..b958139 100644
--- a/doc/connections.rst
+++ b/doc/connection.rst.in
diff --git a/doc/data.rst b/doc/data.rst.in
index ae657c6..ae657c6 100644
--- a/doc/data.rst
+++ b/doc/data.rst.in
diff --git a/doc/deployment.rst.in b/doc/deployment.rst.in
new file mode 100644
index 0000000..f61b83b
--- /dev/null
+++ b/doc/deployment.rst.in
@@ -0,0 +1,2 @@
+Deployments
+===========
diff --git a/doc/hosts.rst b/doc/host.rst.in
index af18d0d..af18d0d 100644
--- a/doc/hosts.rst
+++ b/doc/host.rst.in
diff --git a/doc/image.rst.in b/doc/image.rst.in
new file mode 100644
index 0000000..bbe9f3a
--- /dev/null
+++ b/doc/image.rst.in
@@ -0,0 +1,2 @@
+Remote Lisp images
+==================
diff --git a/doc/index.rst b/doc/index.rst
index 96430cf..5c2f0c8 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -3,21 +3,48 @@ Consfigurator user's manual
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contents:
 
    introduction
    installation
-   tutorial/disk_image
-   tutorial/os_installation
-   connections
-   properties
-   hosts
-   propspecs
-   data
    pitfalls
    news
    ideas
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials
+
+   tutorial/disk_image
+   tutorial/os_installation
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Core
+
+   connection
+   property
+   propspec
+   host
+   combinator
+   deployment
+   data
+   image
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Properties packages
+   :glob:
+
+   property/*
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Utilities packages
+   :glob:
+
+   util
+   util/*
+
 Indices and search
 ==================
 
diff --git a/doc/properties.rst b/doc/property.rst.in
index 265e8f8..265e8f8 100644
--- a/doc/properties.rst
+++ b/doc/property.rst.in
diff --git a/doc/propspecs.rst b/doc/propspec.rst.in
index bec4e6e..bec4e6e 100644
--- a/doc/propspecs.rst
+++ b/doc/propspec.rst.in
diff --git a/doc/tutorial/disk_image.rst b/doc/tutorial/disk_image.rst
index d4b7a20..7001474 100644
--- a/doc/tutorial/disk_image.rst
+++ b/doc/tutorial/disk_image.rst
@@ -1,5 +1,5 @@
-Tutorial: building disk images
-==============================
+Building disk images
+====================
 
 In this tutorial we will show you what properties you need to use to build
 bootable disk images.
diff --git a/doc/tutorial/os_installation.rst b/doc/tutorial/os_installation.rst
index d89ccbf..9e6b077 100644
--- a/doc/tutorial/os_installation.rst
+++ b/doc/tutorial/os_installation.rst
@@ -1,5 +1,5 @@
-Tutorial: OS installation
-=========================
+OS installation
+===============
 
 Consfigurator implements a number of methods for installing operating systems.
 
diff --git a/doc/util.rst.in b/doc/util.rst.in
new file mode 100644
index 0000000..6d39466
--- /dev/null
+++ b/doc/util.rst.in
@@ -0,0 +1,2 @@
+``CONSFIGURATOR`` exported utilities
+====================================