[docs] Add docs on the CMake workflow (#56)

docs/source/advanced-configuration.rst

@@ -294,9 +294,66 @@ Your URI template can use the following variables:
 
 .. tip::
    Instead of using the default of linking to ``_sources``, you can generate Markdown and/or reStructuredText files from your documentation and link to those in ``llms.txt``.
-   See this package's `CMake setup <https://github.com/jdillard/sphinx-llms-txt>`_ for an example of building both HTML and Markdown and/or reStructuredText in parallel.
+   See :ref:`cmake_workflow` for an example of building both HTML and Markdown and/or reStructuredText in parallel.
    Note that ``_sources`` is still needed for ``llms-full.txt`` at this time.
 
+.. _cmake_workflow:
+
+CMake Workflow
+^^^^^^^^^^^^^^
+
+This project uses CMake to orchestrate documentation builds across multiple output formats, serving as a simple demo of the functionality.
+Building multiple formats allows you to compare what works best for your docs, as well as allows users to choose which format to feed to their LLM.
+This approach enables parallel builds and integrates well with CI/CD platforms like Read the Docs.
+
+Key Files
+~~~~~~~~~
+
+.. code-block:: text
+
+   .
+   ├── .readthedocs.yml
+   ├── CMakeLists.txt
+   ├── CMakePresets.json
+   ├── cmake/
+   │   └── SphinxUtils.cmake
+   └── docs/
+       └── CMakeLists.txt
+
+:ghfile:`.readthedocs.yml`
+   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`
+   A CMake config file that sets up the project and includes the ``cmake/`` module path.
+
+:ghfile:`docs/CMakeLists.txt`
+   A CMake config file that includes the Sphinx utilities and defines the documentation-specific build targets.
+
+:ghfile:`cmake/SphinxUtils.cmake`
+   A CMake module that provides Sphinx related utilities.
+
+: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.
+   - **Workflow Presets:** Runs the configure preset followed by the parallel build preset.
+
+Usage
+~~~~~
+
+To build documentation locally using CMake:
+
+.. code-block:: console
+
+   # Run the full workflow (configure + build all formats)
+   cmake --workflow --preset documentation-workflow
+
+   # Or configure and build separately
+   cmake --preset documentation
+   cmake --build --preset html        # Build HTML only
+   cmake --build --preset docs-parallel  # Build all formats
+
 .. _integration_examples:
 
 Integration Examples

docs/source/conf.py

@@ -26,6 +26,10 @@ and a single combined documentation llms-full.txt file, written in reStructuredT
 # This doesn't seem to be supported
 # rst_file_suffix = ".html.rst"
 
+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"])
@@ -56,6 +60,7 @@ extensions = [
     "sphinx_llms_txt",
     "sphinxcontrib.restbuilder",
     "sphinx_inline_tabs",
+    "sphinx.ext.extlinks",
 ]
 
 # The language for content autogenerated by Sphinx. Refer to documentation

docs/source/getting-started.rst

@@ -38,7 +38,7 @@ Choosing an Output Format
 -------------------------
 
 By default, **sphinx-llms-txt** requires no additional configuration and links to raw reStructuredText source files in :confval:`_sources/ <sphinx:html_copy_source>`.
-For optimal LLM support, you can use `sphinx-markdown-builder`_ and/or `sphinxcontrib-restbuilder`_, set up in parallel builds using CMake .
+For optimal LLM support, you can use `sphinx-markdown-builder`_ and/or `sphinxcontrib-restbuilder`_, set up in parallel builds using :ref:`CMake <cmake_workflow>`.
 
 .. list-table:: Output Format Comparison
    :header-rows: 1
@@ -66,11 +66,11 @@ For optimal LLM support, you can use `sphinx-markdown-builder`_ and/or `sphinxco
      - Can lose structure from complex directives
    * - **llms-full.txt support**
      - Suported with above caveats
-     - Pending `support <https://github.com/liran-funaro/sphinx-markdown-builder/pull/37>`_
+     - Pending `support <https://github.com/liran-funaro/sphinx-markdown-builder/pull/37>`__
-     - Pending `support <https://github.com/sphinx-contrib/restbuilder/pull/35>`_
+     - Pending `support <https://github.com/sphinx-contrib/restbuilder/pull/35>`__
 
 
-See the project's `CMake setup <https://github.com/jdillard/sphinx-llms-txt/tree/main/cmake>`_ for an example of building HTML, Markdown, and RST in parallel.
+See :ref:`cmake_workflow` for an example of building HTML, Markdown, and RST in parallel.
 Use :confval:`llms_txt_uri_template` to configure links to point to your preferred format.
 
 .. _sphinx-markdown-builder: https://pypi.org/project/sphinx-markdown-builder/