Declare the documentation's structure in a source file

src/documentation.cpp is the documentation loading source: it carries no
code and names each document that the generated reference contains, in
order, by page label. The labels are declared on each markdown file's
first heading. The build configuration lists the files as Doxygen inputs
and nothing more, so the structure of the documentation and the
mechanics of generating it are separate.

The hand-maintained document index at the end of OVERVIEW.md is gone,
along with the last references to markdown files by filename in the
public header. The document list exists in one place.

The docs target clears its output and scratch directories on every run.
Doxygen keeps output files it judges unchanged, so a run over a
populated scratch directory carried pages forward from earlier ones, and
removed sections survived in the generated HTML and PDF after their
source was edited.

CMakeLists.txt

@@ -188,16 +188,30 @@ if(DOXYGEN_FOUND)
         set(DOXYGEN_GENERATE_LATEX NO)
     endif()
 
-    # The reference is generated from the source and its documentation
-    # comments. The markdown in docs/ is written and read on its own and
-    # stays out of the input.
+    # The prose documents, each rendered as its own page in the generated
+    # reference. Named one per line so the set of documents reaching the
+    # output is stated here instead of implied by a directory.
+    set(DPM_DOC_PAGES
+            ${CMAKE_CURRENT_SOURCE_DIR}/docs/OVERVIEW.md
+            ${CMAKE_CURRENT_SOURCE_DIR}/docs/DESIGN.md
+            ${CMAKE_CURRENT_SOURCE_DIR}/docs/CONSUMERS.md
+            ${CMAKE_CURRENT_SOURCE_DIR}/docs/MODULES.md
+            ${CMAKE_CURRENT_SOURCE_DIR}/docs/BUILD.md
+            ${CMAKE_CURRENT_SOURCE_DIR}/docs/DOCUMENTATION.md
+    )
+
+    # Two kinds of input: include/ and src/ supply the API and internals
+    # reference extracted from the source, DPM_DOC_PAGES supplies the
+    # prose pages.
+    #
     # One target, so `cmake --build <dir> --target docs` is the whole
     # procedure and the IDE lists a single entry for it. The commands
     # below run after Doxygen and place the finished documents.
     doxygen_add_docs(docs
             ${CMAKE_CURRENT_SOURCE_DIR}/include
             ${CMAKE_CURRENT_SOURCE_DIR}/src
-            COMMENT "Generating the code reference with Doxygen"
+            ${DPM_DOC_PAGES}
+            COMMENT "Generating the reference with Doxygen"
     )
 
     if(DPM_DOCS_PDF)
@@ -205,6 +219,8 @@ if(DOXYGEN_FOUND)
         if(PDFLATEX_EXECUTABLE)
             add_custom_command(TARGET docs POST_BUILD
                     COMMAND make -C ${CMAKE_BINARY_DIR}/docs/tmp/latex
+                    COMMAND ${CMAKE_COMMAND} -E rm -rf
+                            ${CMAKE_BINARY_DIR}/docs/pdf
                     COMMAND ${CMAKE_COMMAND} -E copy
                             ${CMAKE_BINARY_DIR}/docs/tmp/latex/refman.pdf
                             ${CMAKE_BINARY_DIR}/docs/pdf/dpm-core-${PROJECT_VERSION}.pdf
@@ -217,12 +233,23 @@ if(DOXYGEN_FOUND)
 
     if(DPM_DOCS_HTML)
         add_custom_command(TARGET docs POST_BUILD
+                COMMAND ${CMAKE_COMMAND} -E rm -rf
+                        ${CMAKE_BINARY_DIR}/docs/html
                 COMMAND ${CMAKE_COMMAND} -E copy_directory
                         ${CMAKE_BINARY_DIR}/docs/tmp/html
                         ${CMAKE_BINARY_DIR}/docs/html
                 COMMENT "Placing the HTML reference"
         )
     endif()
+
+    # Doxygen keeps output files it judges unchanged, so a run over a
+    # populated scratch directory can carry pages forward from an earlier
+    # one. Removing it here means the next run regenerates everything,
+    # and leaves docs/ holding the finished documents alone.
+    add_custom_command(TARGET docs POST_BUILD
+            COMMAND ${CMAKE_COMMAND} -E rm -rf ${CMAKE_BINARY_DIR}/docs/tmp
+            COMMENT "Clearing the generators' scratch directory"
+    )
 endif()
 
 # ---------------------------------------------------------------------