remove inline configuration directives

bkietz · Oct 26, 2024 · 29eebc2 · 29eebc2
1 parent 8baea8d
commit 29eebc2
Show file tree

Hide file tree

Showing 10 changed files with 189 additions and 252 deletions.
diff --git a/TODO.md b/TODO.md
@@ -168,41 +168,6 @@ could be adoted, or you could write the module block verbatim inside
 an `#if false`- maud_scan would read it even if nothing else did.
 
 
-TODO: get python review for sphinx hackery
-------------------------------------------
-
-On the one hand, I greatly prefer the idea of inline conf.py (see below).
-On the other hand, this might be unforgivably weird to existing users of
-sphinx. I need a more expert opinion.
-
-##### opinions
-
-To me, any file which is *intended* to be singular across a project is
-highly suspect. This implies that it's automatically part of the
-"bare minimum starter boilerplate" which I'm trying to minimize here.
-It also implies nonlocality; whatever is in that file might only be
-relevant to something far away. In the example of sphinx, conf.py
-frequently contains blocks which are only relevant to
-`some/nested/dir/index.rst`. Then often as not we "tidy" up conf.py by
-adding comments like `# (used in some/nested/dir/)`.
-
-On the other hand, conf.py is absolutely singular (discounting
-extensions etc). Hiding that's dangerous even if FUD would be the only cost,
-but it *could* also suggest to someone that (as with .clang-format) different
-subdirectories can have different configs which is manifestly not correct, or
-that the working directory for the fragment is the directory containing the
-fragment (probably not). Also, of potentially equal smelliness is the standard
-prelude which is implied by fragmenting conf.py 
-
-Would it be better to have fragments which weren't embedded in rst files?
-`**/sphinx.conf.py`?
-
-Would it be better to pass them all through `.in2` so that sphinx config
-values can be drawn from CMake state? That would at least make it more
-easily *optional*, with pretty easy extension and opt-out from the default
-prelude.
-
-
 TODO: consolidate tests
 -----------------------
 

diff --git a/cmake_modules/Maud.cmake b/cmake_modules/Maud.cmake
@@ -1079,19 +1079,54 @@ function(_maud_setup_doc)
     return()
   endif()
 
+  # TODO document that conf can't be generated
+  glob(
+    _MAUD_SPHINX_CONF
+    CONFIGURE_DEPENDS
+    EXCLUDE_RENDERED
+    "(^|/)sphinx_configuration/conf.py$"
+  )
+  if(_MAUD_SPHINX_CONF MATCHES "^(.*;.*|)$")
+    # TODO if no conf.py is found, dump a decent default into the source tree
+    message(FATAL_ERROR "Sphinx requires exactly one conf.py file but found '${_MAUD_SPHINX_CONF}'")
+    return()
+  endif()
+  cmake_path(GET _MAUD_SPHINX_CONF PARENT_PATH conf_dir)
+
   set(doc "${CMAKE_BINARY_DIR}/documentation")
 
   file(REMOVE_RECURSE "${doc}")
   file(MAKE_DIRECTORY "${doc}/stage")
+  # TODO verify that this link is sufficient to literalinclude and document it
   file(CREATE_LINK "${CMAKE_SOURCE_DIR}" "${doc}/stage/CMAKE_SOURCE_DIR" SYMBOLIC)
 
+  file(
+    WRITE "${MAUD_DIR}/maud_sphinx_helper/pyproject.toml"
+    [[
+      [build-system]
+      requires = ["setuptools"]
+      build-backend = "setuptools.build_meta"
+      [project]
+      name = "maud"
+      version = "0.0.1"
+      dependencies = []
+    ]]
+  )
+  configure_file(
+    "${_MAUD_SELF_DIR}/maud_sphinx_helper.py.in"
+    "${MAUD_DIR}/maud_sphinx_helper/maud/__init__.py"
+    NO_SOURCE_PERMISSIONS
+    @ONLY
+  )
+
   add_custom_command(
     OUTPUT "${doc}/venv/pip.report.json"
     DEPENDS "${_MAUD_SELF_DIR}/sphinx_requirements.txt"
     COMMAND
       Python3::Interpreter -m venv --clear "${doc}/venv"
     COMMAND
       "${doc}/venv/bin/pip" install
+      "${MAUD_DIR}/maud_sphinx_helper"
       --requirement "${_MAUD_SELF_DIR}/sphinx_requirements.txt"
       --isolated
       --require-virtualenv
@@ -1101,7 +1136,6 @@ function(_maud_setup_doc)
       --quiet
       --log "${doc}/venv/pip.log"
       --report "${doc}/venv/pip.report.json"
-    # TODO pip install --editable apidoc module
     COMMENT "Building virtual env ${doc}/venv for Sphinx"
   )
   set(SPHINX_BUILD "${doc}/venv/bin/sphinx-build")
@@ -1163,32 +1197,10 @@ function(_maud_setup_doc)
       COMMENT "Staging${file}$<$<BOOL:${is_gen}>: (generated)> to ${staged}"
     )
     list(APPEND all_staged "${staged}")
-
-    add_custom_command(
-      OUTPUT "${staged}.conf.py"
-      DEPENDS "${file}"
-      WORKING_DIRECTORY "${doc}"
-      COMMAND
-        "${CMAKE_COMMAND}"
-        "-DRST_FILE=${file}"
-        "-DCONF_FILE=${staged}.conf.py"
-        -P "${MAUD_DIR}/eval.cmake"
-        -- "_maud_sphinx_conf()"
-      VERBATIM
-      COMMENT "Extracting inline configuration from ${file} to ${staged}.conf.py"
-    )
-    list(APPEND all_staged "${staged}.conf.py")
   endforeach()
 
   # TODO assert there are no dupes in all_staged = collision between source/generated
 
-  add_custom_command(
-    OUTPUT "${doc}/stage/conf.py"
-    DEPENDS "${_MAUD_SELF_DIR}/sphinx_conf.py"
-    COMMAND "${CMAKE_COMMAND}" -E copy "${_MAUD_SELF_DIR}/sphinx_conf.py" "${doc}/stage/conf.py"
-    COMMENT "Staging conf prelude"
-  )
-
   add_custom_target(documentation ALL)
 
   set(all_build_logs)
@@ -1219,10 +1231,18 @@ function(_maud_setup_doc)
         "${doc}/venv/pip.report.json"
         ${all_staged}
         ${all_apidoc}
-        "${doc}/stage/conf.py"
+        # FIXME sphinx doesn't check the mtime of conf.py; it will only rebuild
+        # if the pickled configuration has changed. That's not great for
+        # interactive development; it'd be better if modifying conf.py
+        # invalidated the whole doc build. Maybe add a config value which is
+        # the mtime of conf.py? Or better, have the command use --write-all --fresh-env
+        # if any configuration file has changed
+        "${conf_dir}/conf.py"
       WORKING_DIRECTORY "${doc}"
       COMMAND
-        "${SPHINX_BUILD}" --builder ${builder}
+        "${SPHINX_BUILD}"
+        --builder ${builder}
+        --conf-dir "${conf_dir}"
         stage
         ${builder}
         > ${builder}.log
@@ -1245,39 +1265,6 @@ function(_maud_line_count string out_var)
 endfunction()
 
 
-function(_maud_sphinx_conf)
-  file(READ "${RST_FILE}" content)
-
-  string(CONCAT pattern "^(.*\n)" [[\.\. configuration::]] "\n+( +)(.*)$")
-
-  set(conf "")
-
-  while(content MATCHES "${pattern}")
-    set(content "${CMAKE_MATCH_1}")
-    set(indent "${CMAKE_MATCH_2}")
-    set(directive "${CMAKE_MATCH_3}")
-
-    if(directive MATCHES "^[^\n]*(\n${indent}[^\n]*)+")
-      set(directive "${CMAKE_MATCH_0}")
-    endif()
-    string(REGEX REPLACE "\n${indent}" "\n" directive "${directive}")
-
-    set(line_num 1)
-    _maud_line_count("${content}" line_inc)
-    math_assign(line_num + ${line_inc})
-    string(PREPEND directive "\n# BEGIN ${RST_FILE}:${line_num}\n")
-
-    _maud_line_count("${directive}" line_inc)
-    math_assign(line_num + ${line_inc})
-    string(APPEND directive "\n# END ${RST_FILE}:${line_num}\n")
-
-    string(PREPEND conf "${directive}\n")
-  endwhile()
-
-  file(WRITE "${CONF_FILE}" "${conf}\n")
-endfunction()
-
-
 function(shim_script_as destination script)
   cmake_path(ABSOLUTE_PATH script)
 

diff --git a/cmake_modules/maud_sphinx_helper.py.in b/cmake_modules/maud_sphinx_helper.py.in
@@ -0,0 +1,11 @@
+from pathlib import Path
+
+STAGE_DIR = Path("@doc@/stage")
+CONF_DIR = Path("@conf_dir@")
+APIDOC_DIR = Path("@doc@/apidoc")
+CMAKE_SOURCE_DIR = Path("@CMAKE_SOURCE_DIR@")
+project = "@PROJECT_NAME@"
+
+
+def setup(app):
+    print("set up maud extension")
diff --git a/cmake_modules/sphinx_conf.py b/cmake_modules/sphinx_conf.py
diff --git a/documentation.rst b/documentation.rst
@@ -24,6 +24,11 @@ Which builders are used can be controlled via ``option(SPHINX_BUILDERS)``,
 which defaults to building just ``dirhtml``. To disable building
 documentation, set this to an empty string.
 
+Sphinx configuration (minimally, your ``conf.py``) should be put in a directory
+named ``sphinx_configuration/`` anywhere in your project.
+
+.. TODO talk about import maud, requirements.txt, venv, ...
+
 
 API doc
 =======
@@ -54,19 +59,6 @@ note for those who have used other apidoc systems: cross references from
 ``///`` comments to labels defined in .rst will just work.
 
 
-Configuration
-=============
-
-Sphinx is usually configured with a single ``conf.py`` script.
-Maud provides a directive to specify configuration inline from ``.rst``
-files:
-
-.. code-block:: rst
-
-  .. configuration::
-
-    html_theme = 'furo'
-
 ``.in2`` Templates
 ~~~~~~~~~~~~~~~~~~
 

diff --git a/index.rst b/index.rst
@@ -293,53 +293,3 @@ Table of Contents
   :glob:
 
   *
-
-.. TODO allow the configuration directive to name a file
-
-.. configuration::
-
-    author = "Benjamin Kietzman <[email protected]>"
-
-    html_title = "Maud"
-    html_theme = "furo"
-    html_theme_options = {
-        "footer_icons": [
-            {
-                "name": "GitHub",
-                "url": "https://github.com/bkietz/maud",
-                "html": """
-                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
-                  <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
-                </svg>
-              """,
-                "class": "",
-            },
-        ],
-        "top_of_page_buttons": ["view", "edit"],
-        "navigation_with_keys": True,
-    }
-    html_context = {
-        "github_user": "bkietz",
-        "github_repo": "maud",
-        "github_version": "trunk",
-        "doc_path": "",
-    }
-
-    pygments_style = "default"
-    pygments_dark_style = "monokai"
-
-    extensions += ["sphinx.ext.autosectionlabel"]
-    autosectionlabel_maxdepth = 2
-    autosectionlabel_prefix_document = True
-
-    extensions += ["sphinx.ext.duration"]
-    extensions += ["sphinx_inline_tabs"]
-
-    extensions += ["sphinx.ext.extlinks"]
-    extlinks_detect_hardcoded_links = True
-    extlinks = {
-        **(extlinks if 'extlinks' in globals() else {}),
-        "cxx20": ("https://timsong-cpp.github.io/cppwp/n4868/%s", "CXX(20:%s)"),
-        # TODO this should be intersphinx instead
-        "cmake": ("https://cmake.org/cmake/help/latest/%s", None),
-    }
diff --git a/install.cmake b/install.cmake
@@ -13,7 +13,7 @@ install(
   "${dir}/cmake_modules/test_.cxx"
   "${dir}/cmake_modules/test_.hxx"
   "${dir}/cmake_modules/test_main_.cxx"
-  "${dir}/cmake_modules/sphinx_conf.py"
+  "${dir}/cmake_modules/maud_sphinx_helper.py.in"
   "${dir}/cmake_modules/maud_apidoc.py"
   "${dir}/cmake_modules/sphinx_requirements.txt"
   DESTINATION