diff --git a/docs/source/advanced-configuration.rst b/docs/source/advanced-configuration.rst index 8d6411a..5839d5e 100644 --- a/docs/source/advanced-configuration.rst +++ b/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 `_ 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 diff --git a/docs/source/conf.py b/docs/source/conf.py index de320c1..de0b623 100644 --- a/docs/source/conf.py +++ b/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 diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst index e5335cd..f5f6c0c 100644 --- a/docs/source/getting-started.rst +++ b/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/ `. -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 `. .. 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 `_ - - Pending `support `_ + - Pending `support `__ + - Pending `support `__ -See the project's `CMake setup `_ 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/