[docs] Use FetchContent to grab CMake modules (#61)

CMakeLists.txt

@@ -1,8 +1,15 @@
 cmake_minimum_required(VERSION 3.15)
 project(SphinxLLMsTxt VERSION 1.0.0 LANGUAGES NONE)
 
-# Add CMake module path
+# Fetch Sphinx CMake modules
-list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+include(FetchContent)
+FetchContent_Declare(
+  sphinx_cmake_modules
+  GIT_REPOSITORY https://github.com/jdillard/sphinx-cmake-modules.git
+  GIT_TAG        main
+)
+FetchContent_MakeAvailable(sphinx_cmake_modules)
+list(APPEND CMAKE_MODULE_PATH "${sphinx_cmake_modules_SOURCE_DIR}")
 
 # Add documentation
 add_subdirectory(docs)

CMakePresets.json

@@ -29,7 +29,7 @@
     },
     {
       "name": "docs-parallel",
-      "displayName": "Build HTML and Markdown in parallel",
+      "displayName": "Build all output formats in parallel",
       "configurePreset": "documentation",
       "targets": ["html", "markdown", "rst"]
     }

cmake/SphinxUtils.cmake

@@ -1,28 +0,0 @@
-# Sphinx related utilities
-
-set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/source)
-set(SPHINX_BUILD ${CMAKE_BINARY_DIR})
-
-# Function to find Sphinx in the system
-function(setup_sphinx_environment)
-    # Find sphinx-build executable in system
-    find_program(SPHINX_EXECUTABLE
-        NAMES sphinx-build
-        DOC "Sphinx documentation generator"
-    )
-
-    if(NOT SPHINX_EXECUTABLE)
-        message(FATAL_ERROR "sphinx-build not found. Please install Sphinx.")
-    endif()
-
-    # Export to parent scope
-    set(SPHINX_EXECUTABLE "${SPHINX_EXECUTABLE}" PARENT_SCOPE)
-endfunction()
-
-# Function to add a Sphinx builder target
-function(add_sphinx_builder builder_name)
-    add_custom_target(${builder_name}
-        COMMAND ${SPHINX_EXECUTABLE} -b ${builder_name} ${SPHINX_SOURCE} ${SPHINX_BUILD}/${builder_name}
-        VERBATIM
-    )
-endfunction()

docs/requirements.txt

@@ -2,6 +2,7 @@ furo
 esbonio
 sphinx-contributors
 sphinx
+sphinx-design
 sphinx-llms-txt
 sphinx-inline-tabs
 sphinxext-opengraph

docs/source/advanced-configuration.rst

@@ -311,36 +311,113 @@ Use :confval:`llms_txt_uri_template` to configure links to point to your preferr
 Key Files
 ~~~~~~~~~
 
+These configuration files serve as a simple example of a Sphinx site hosted on Read The Docs, some modification may be needed.
+
 .. code-block:: text
 
    .
    ├── .readthedocs.yml
    ├── CMakeLists.txt
    ├── CMakePresets.json
-   ├── cmake/
-   │   └── SphinxUtils.cmake
    └── docs/
        └── CMakeLists.txt
 
-:ghfile:`.readthedocs.yml`
+Each section below contains a summary of the file's purpose, the full contents of the file, and a table describing key lines that may need modification.
+
+.. dropdown:: .readthedocs.yml
+   :chevron: down-up
+
    A Read The Docs config file that installs dependencies, then runs the full documentation workflow which builds all output formats in parallel, and copies them into a single deploy location.
 
-:ghfile:`CMakeLists.txt`
+   .. literalinclude:: ../../.readthedocs.yml
-   A CMake config file that sets up the project and includes the ``cmake/`` module path.
+      :language: yaml
+      :lines: 1-9,11,14-
+      :linenos:
+      :emphasize-lines: 9, 14-15
 
-:ghfile:`docs/CMakeLists.txt`
+   .. list-table::
-   A CMake config file that includes the Sphinx utilities and defines the documentation-specific build targets.
+      :header-rows: 1
+      :width: 100%
+      :widths: 15 85
 
-:ghfile:`cmake/SphinxUtils.cmake`
+      * - Line
-   A CMake module that provides Sphinx related utilities.
+        - Description
+      * - **9**
+        - Update the path if your requirements file is in a different location
+      * - **13-14**
+        - Modify the copy commands for the output formats you deploy
+
+.. dropdown:: CMakeLists.txt
+   :chevron: down-up
+
+   A CMake config file that sets up the project, fetches the shared `sphinx-cmake-modules <https://github.com/jdillard/sphinx-cmake-modules>`_, and includes the docs subdirectory.
+
+   .. literalinclude:: ../../CMakeLists.txt
+      :language: cmake
+      :linenos:
+      :emphasize-lines: 9, 15
+
+   .. list-table::
+      :header-rows: 1
+      :width: 100%
+      :widths: 15 85
+
+      * - Line
+        - Description
+      * - **9**
+        - Update the ``GIT_TAG`` to use a different version or commit hash
+      * - **15**
+        - Change if your docs subdirectory has a different location
+
+.. dropdown:: docs/CMakeLists.txt
+   :chevron: down-up
+
+   A CMake config file that includes the `SphinxUtils <https://github.com/jdillard/sphinx-cmake-modules/blob/v0.1.0/SphinxUtils.cmake>`_ module from FetchContent and defines the documentation-specific build targets.
+
+   .. literalinclude:: ../CMakeLists.txt
+      :language: cmake
+      :linenos:
+      :emphasize-lines: 5-7
+
+   .. list-table::
+      :header-rows: 1
+      :width: 100%
+      :widths: 15 85
+
+      * - Line
+        - Description
+      * - **5-7**
+        - Add or remove calls based on which output formats you need
+
+
+.. dropdown:: CMakePresets.json
+   :chevron: down-up
 
-:ghfile:`CMakePresets.json`
    Defines presets for configuring and building documentation:
 
    - **Configure Presets:** Sets up the build directory.
-   - **Build Presets:** Defines Build formats individually and all in parallel.
+   - **Build Presets:** Defines build formats individually and all in parallel.
    - **Workflow Presets:** Runs the configure preset followed by the parallel build preset.
 
+   .. literalinclude:: ../../CMakePresets.json
+      :language: json
+      :linenos:
+      :emphasize-lines: 18-23, 24-29, 34
+
+   .. list-table::
+      :header-rows: 1
+      :width: 100%
+      :widths: 15 85
+
+      * - Line
+        - Description
+      * - **18-23**
+        - Remove this preset to disable Markdown documentation builds
+      * - **24-29**
+        - Remove this preset to disable reStructuredText documentation builds
+      * - **34**
+        - Modify the targets list to build only the output formats you need in parallel
+
 Usage
 ~~~~~
 

docs/source/conf.py

@@ -26,10 +26,6 @@ and a single combined documentation llms-full.txt file, written in reStructuredT
 # rst_file_suffix = ".html.rst"
 markdown_file_suffix = ".html.md"
 
-extlinks = {
-    "ghfile": ("https://github.com/jdillard/sphinx-llms-txt/blob/main/%s", "%s")
-}
-
 # check if the current commit is tagged as a release (vX.Y.Z)
 try:
     GIT_TAG_OUTPUT = subprocess.check_output(["git", "tag", "--points-at", "HEAD"])
@@ -61,6 +57,7 @@ extensions = [
     "sphinxcontrib.restbuilder",
     "sphinx_inline_tabs",
     "sphinx.ext.extlinks",
+    "sphinx_design",
 ]
 
 # The language for content autogenerated by Sphinx. Refer to documentation