Documentation using Sphinx

.cspell.json

@@ -1,5 +1,9 @@
 {
     "words": [
+        "dedent",
+        "doxygen",
+        "literalinclude",
+        "toctree",
         "64kminus1",
         "ALTSVC",
         "anyhttp",

.devcontainer/Dockerfile

@@ -16,6 +16,20 @@ RUN apt-get update && export DEBIAN_FRONTEND=noninteractive && \
 
 # ==================================================================================================
 
+#
+# What makes the documentation (cmake --build build --target docs): Doxygen for the comments in the
+# headers, Sphinx for the pages. These are the versions of the release of Debian that the base image
+# is on, which are known to work together. The Documentation job in .github/workflows/release.yml
+# installs the same.
+#
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive && \
+    apt-get -y install --no-install-recommends \
+        doxygen python3-sphinx python3-breathe python3-sphinx-rtd-theme && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# ==================================================================================================
+
 #
 # enable persistent bash history in container
 #

.github/instructions/anyhttp.instructions.md

@@ -37,7 +37,7 @@ Builds are out-of-source, one tree per configuration (`build/` Debug, `build-rel
 Run the tests from the repository root -- they load TLS material through relative paths -- and
 prefer `gtest-parallel build/test/test_all`.
 
-[README.md](../../README.md) documents the API, the concurrency model and the reasoning behind it:
+[docs/](../../docs/README.md) documents the API, the concurrency model and the reasoning behind it:
 read it before changing anything about request/response semantics.
 [CLAUDE.md](../../CLAUDE.md) covers working in the tree in detail -- the build trees and their
 options, how to run and filter the tests, the sanitizer recipes, the source layout and the traps.

.github/workflows/release.yml

@@ -132,8 +132,45 @@ jobs:
       - name: Check installing and embedding
         run: scripts/check_package.sh
 
+  #
+  # The guide and the reference, with Doxygen and Sphinx, where warnings are errors: this is where a
+  # public symbol without a comment shows, and a reference that goes nowhere. The tools are the
+  # ones .devcontainer/Dockerfile installs, as the image does not have them. Nothing is compiled.
+  #
+  docs:
+    name: Documentation
+    runs-on: *runs_on
+    container: *container
+
+    steps:
+      - *checkout
+
+      - name: Install the tools
+        run: |
+          apt-get update
+          apt-get -y install --no-install-recommends \
+            doxygen python3-sphinx python3-breathe python3-sphinx-rtd-theme
+
+      - name: Make the documentation
+        run: |
+          cmake --preset build
+          cmake --build --preset build --target docs
+
+      - name: Upload the documentation
+        uses: actions/upload-artifact@v7
+        with:
+          name: documentation
+          path: build/docs/html/
+          retention-days: 30
+
+  #
+  # A site has one deployment, so this is what publishes the documentation as well: it goes to the
+  # root of the site, and the coverage report next to it. There is no point in publishing a report
+  # without the documentation, so a failure over there holds this back.
+  #
   coverage:
     name: Coverage
+    needs: docs
     runs-on: *runs_on
     container: *container
     permissions:
@@ -160,14 +197,21 @@ jobs:
           mkdir -p pages/coverage
           cp -r build/coverage_report/* pages/coverage/
 
+      - name: Get the documentation
+        if: github.ref == 'refs/heads/master' && github.event_name == 'push'
+        uses: actions/download-artifact@v8
+        with:
+          name: documentation
+          path: pages/
+
       - name: Upload Coverage Report
         uses: actions/upload-artifact@v7
         with:
           name: coverage-report
           path: build/coverage_report/
           retention-days: 30
 
-      - name: Upload coverage to GitHub Pages
+      - name: Upload coverage and documentation to GitHub Pages
         if: github.ref == 'refs/heads/master' && github.event_name == 'push'
         uses: actions/upload-pages-artifact@v5
         with:

CLAUDE.md

@@ -1,8 +1,10 @@
 # Working on anyhttp
 
-C++23 HTTP/1.1 + HTTP/2 + HTTP/3 server and client on top of Boost.Asio. [README.md](README.md)
-describes the API, the concurrency model and the reasoning behind it -- read it before changing
-anything about request/response semantics. This file is about *how to work in the tree*.
+C++23 HTTP/1.1 + HTTP/2 + HTTP/3 server and client on top of Boost.Asio. [docs/](docs/README.md)
+has the API, the concurrency model and the reasoning behind it, in
+[programmers-guide.rst](docs/programmers-guide.rst), [end-of-body.rst](docs/end-of-body.rst) and
+[concurrent-requests.rst](docs/concurrent-requests.rst) -- read them before changing anything about
+request/response semantics. This file is about *how to work in the tree*.
 
 ## Build and test
 
@@ -89,6 +91,15 @@ Parametrized tests are suffixed `/HTTP11`, `/HTTP2`, `/HTTP3` -- not h2/h3. `--g
 only `*` and `?`, and a filter that matches nothing exits 0 with no output, which reads like a
 pass: check for `[ OK ]` lines.
 
+### Documentation
+
+`cmake --build build --target docs` makes the site in `build/docs/html`; the pages are `docs/*.rst`,
+the reference comes from the comments in the public headers. [docs/README.md](docs/README.md) has
+how to write it. Warnings are errors in Doxygen and Sphinx, so changing a public header can fail this
+target: run it, a new public symbol also needs an entry in `docs/reference.rst`. The code the guide
+shows is `docs/snippets.cpp` and `docs/examples/`, compiled in every tree with
+`ANYHTTP_BUILD_DOCS` and run by `test/test_docs.cpp`. Change it there, never in a page.
+
 ### Sanitizers
 
 Separate trees; the sanitizer options in the Debug branch of `CMakeLists.txt` are commented out on

CMakeLists.txt

@@ -17,6 +17,9 @@ option(ENABLE_COVERAGE "Enable coverage flags and llvm-cov target" OFF)
 option(ANYHTTP_BUILD_TESTS "Build the tests" ${PROJECT_IS_TOP_LEVEL})
 option(ANYHTTP_BUILD_APPS "Build the programs" ${PROJECT_IS_TOP_LEVEL})
 option(ANYHTTP_INSTALL "Generate install rules" ${PROJECT_IS_TOP_LEVEL})
+option(ANYHTTP_BUILD_DOCS
+       "Build the code of the guide, and add the 'docs' target where Doxygen and Sphinx are there"
+       ${PROJECT_IS_TOP_LEVEL})
 
 if (DEFINED ENV{GITHUB_ACTIONS})
     add_compile_definitions(GITHUB_ACTIONS)
@@ -241,6 +244,10 @@ if (ANYHTTP_BUILD_TESTS)
     add_subdirectory(test)
 endif()
 
+if (ANYHTTP_BUILD_DOCS)
+    add_subdirectory(docs)
+endif()
+
 if (ANYHTTP_INSTALL)
     include(cmake/install.cmake)
 endif()

CMakePresets.json

@@ -278,14 +278,15 @@
         {
             "name": "build-deploy",
             "displayName": "For cmake --install",
-            "description": "Release, without the tests and thus without cfssl and the test PKI. On AWS-LC, which links statically: a TLS library the target machine does not have to provide",
+            "description": "Release, without the tests and thus without cfssl and the test PKI, and without the code of the guide. On AWS-LC, which links statically: a TLS library the target machine does not have to provide",
             "inherits": [
                 "clang",
                 "base"
             ],
             "cacheVariables": {
                 "CMAKE_BUILD_TYPE": "Release",
-                "ANYHTTP_BUILD_TESTS": "OFF"
+                "ANYHTTP_BUILD_TESTS": "OFF",
+                "ANYHTTP_BUILD_DOCS": "OFF"
             }
         }
     ],