From 543efabebbe9f318b89cee08fd68f627b4c0e97d Mon Sep 17 00:00:00 2001 From: Jared Dillard Date: Mon, 1 Dec 2025 13:34:45 -0800 Subject: [PATCH] [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