From 543efabebbe9f318b89cee08fd68f627b4c0e97d Mon Sep 17 00:00:00 2001 From: Jared Dillard Date: Mon, 1 Dec 2025 13:34:45 -0800 Subject: [PATCH 1/2] [docs] Add restbuilder builder for single page `.rst` builds (#53) --- CMakePresets.json | 8 +++++++- docs/CMakeLists.txt | 7 +++++++ docs/requirements.txt | 1 + docs/source/advanced-configuration.rst | 4 ++-- docs/source/conf.py | 5 +++++ 5 files changed, 22 insertions(+), 3 deletions(-) diff --git a/CMakePresets.json b/CMakePresets.json index 8e2f1c3..1336542 100644 --- a/CMakePresets.json +++ b/CMakePresets.json @@ -21,11 +21,17 @@ "configurePreset": "documentation", "targets": ["markdown"] }, + { + "name": "rst", + "displayName": "Build reStructuredText Documentation", + "configurePreset": "documentation", + "targets": ["rst"] + }, { "name": "docs-parallel", "displayName": "Build HTML and Markdown in parallel", "configurePreset": "documentation", - "targets": ["html", "markdown"] + "targets": ["html", "markdown", "rst"] } ], "workflowPresets": [ diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 2204fbb..fbb1baa 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -18,3 +18,10 @@ add_custom_target(markdown COMMENT "Building Markdown documentation" VERBATIM ) + +# Build reStructuredText documentation +add_custom_target(rst + COMMAND ${SPHINX_EXECUTABLE} -b rst ${SPHINX_SOURCE} ${SPHINX_BUILD} + COMMENT "Building reStructuredText documentation" + VERBATIM +) diff --git a/docs/requirements.txt b/docs/requirements.txt index 98f1a95..6f7cb11 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -5,3 +5,4 @@ sphinx sphinx-llms-txt sphinxext-opengraph sphinx-markdown-builder +sphinxcontrib-restbuilder diff --git a/docs/source/advanced-configuration.rst b/docs/source/advanced-configuration.rst index b855551..8d6411a 100644 --- a/docs/source/advanced-configuration.rst +++ b/docs/source/advanced-configuration.rst @@ -293,8 +293,8 @@ Your URI template can use the following variables: - ``{sourcelink_suffix}`` - The suffix from ``html_sourcelink_suffix`` configuration (e.g., ``.txt``) .. tip:: - Instead of using the default of linking to ``_sources``, you can generate Markdown 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 in parallel. + 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. Note that ``_sources`` is still needed for ``llms-full.txt`` at this time. .. _integration_examples: diff --git a/docs/source/conf.py b/docs/source/conf.py index e3f3f76..b9f9dfb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -15,6 +15,7 @@ import subprocess project = "sphinx-llms-txt" copyright = "Jared Dillard" author = "Jared Dillard" + llms_txt_uri_template = "{base_url}{docname}.md" llms_txt_code_files = ["+:../../sphinx_llms_txt/*.py"] llms_txt_summary = """ @@ -22,6 +23,9 @@ A Sphinx extension that generates a summary llms.txt file,written in Markdown, and a single combined documentation llms-full.txt file, written in reStructuredText. """ +# This doesn't seem to be supported +# rst_file_suffix = ".html.rst" + # 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"]) @@ -50,6 +54,7 @@ extensions = [ "sphinx.ext.intersphinx", "sphinx_contributors", "sphinx_llms_txt", + "sphinxcontrib.restbuilder", ] # The language for content autogenerated by Sphinx. Refer to documentation From db32dc60a7faa8fd2b760fff68ebf30d01a55350 Mon Sep 17 00:00:00 2001 From: Jared Dillard Date: Tue, 2 Dec 2025 16:36:14 -0800 Subject: [PATCH 2/2] Improve CMake bits --- .readthedocs.yml | 4 ++- .../{SetupSphinx.cmake => SphinxUtils.cmake} | 13 +++++++- docs/CMakeLists.txt | 30 ++++--------------- 3 files changed, 20 insertions(+), 27 deletions(-) rename cmake/{SetupSphinx.cmake => SphinxUtils.cmake} (54%) diff --git a/.readthedocs.yml b/.readthedocs.yml index e90e042..6731102 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -11,4 +11,6 @@ build: - cmake --workflow --preset documentation-workflow # Copy built documentation to Read the Docs output directory - mkdir -p $READTHEDOCS_OUTPUT/html - - cp -r build/* $READTHEDOCS_OUTPUT/html/ + - cp -r build/html/* $READTHEDOCS_OUTPUT/html/ + - cp -r build/markdown/* $READTHEDOCS_OUTPUT/html/ + - cp -r build/rst/* $READTHEDOCS_OUTPUT/html/ diff --git a/cmake/SetupSphinx.cmake b/cmake/SphinxUtils.cmake similarity index 54% rename from cmake/SetupSphinx.cmake rename to cmake/SphinxUtils.cmake index 4ec7466..2277f66 100644 --- a/cmake/SetupSphinx.cmake +++ b/cmake/SphinxUtils.cmake @@ -1,4 +1,7 @@ -# SetupSphinx.cmake - Find Sphinx for CI environments +# 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) @@ -15,3 +18,11 @@ function(setup_sphinx_environment) # 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() diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index fbb1baa..ceb18ac 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -1,27 +1,7 @@ -# Find Sphinx -include(SetupSphinx) +include(SphinxUtils) + setup_sphinx_environment() -set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR}/source) -set(SPHINX_BUILD ${CMAKE_BINARY_DIR}) - -# Build HTML documentation -add_custom_target(html - COMMAND ${SPHINX_EXECUTABLE} -b html ${SPHINX_SOURCE} ${SPHINX_BUILD} - COMMENT "Building HTML documentation" - VERBATIM -) - -# Build markdown documentation -add_custom_target(markdown - COMMAND ${SPHINX_EXECUTABLE} -b markdown ${SPHINX_SOURCE} ${SPHINX_BUILD} - COMMENT "Building Markdown documentation" - VERBATIM -) - -# Build reStructuredText documentation -add_custom_target(rst - COMMAND ${SPHINX_EXECUTABLE} -b rst ${SPHINX_SOURCE} ${SPHINX_BUILD} - COMMENT "Building reStructuredText documentation" - VERBATIM -) +add_sphinx_builder(html) +add_sphinx_builder(markdown) +add_sphinx_builder(rst)