Merge branch 'main' into feature/singlemarkdown

.readthedocs.yml

@@ -11,4 +11,7 @@ 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 build/singlemarkdown/index.md $READTHEDOCS_OUTPUT/html/llms-full.txt
+    - cp -r build/rst/* $READTHEDOCS_OUTPUT/html/

CMakePresets.json

@@ -21,11 +21,23 @@
       "configurePreset": "documentation",
       "targets": ["markdown"]
     },
+    {
+      "name": "singlemarkdown",
+      "displayName": "Build Single Markdown Documentation",
+      "configurePreset": "documentation",
+      "targets": ["singlemarkdown"]
+    },
+    {
+      "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", "singlemarkdown", "rst"]
     }
   ],
   "workflowPresets": [

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)
@@ -12,16 +15,14 @@ function(setup_sphinx_environment)
         message(FATAL_ERROR "sphinx-build not found. Please install Sphinx.")
     endif()
 
-    # Get Sphinx version
-    execute_process(
-        COMMAND ${SPHINX_EXECUTABLE} --version
-        OUTPUT_VARIABLE SPHINX_VERSION_OUTPUT
-        ERROR_VARIABLE SPHINX_VERSION_OUTPUT
-        OUTPUT_STRIP_TRAILING_WHITESPACE
-    )
-    message(STATUS "Found Sphinx: ${SPHINX_EXECUTABLE}")
-    message(STATUS "${SPHINX_VERSION_OUTPUT}")
-
     # 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/CMakeLists.txt

@@ -1,24 +1,8 @@
-# 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 both formats
-add_custom_target(docs ALL)
-add_dependencies(docs html markdown)
+add_sphinx_builder(html)
+add_sphinx_builder(markdown)
+add_sphinx_builder(singlemarkdown)
+add_sphinx_builder(rst)

docs/requirements.txt

@@ -3,5 +3,7 @@ esbonio
 sphinx-contributors
 sphinx
 sphinx-llms-txt
+sphinx-inline-tabs
 sphinxext-opengraph
-sphinx-markdown-builder
+sphinx-markdown-builder @ git+https://github.com/akaihola/sphinx-markdown-builder.git@singlemarkdown
+sphinxcontrib-restbuilder

docs/source/advanced-configuration.rst

@@ -292,6 +292,11 @@ Your URI template can use the following variables:
 - ``{suffix}`` - The source file suffix (e.g., ``.rst``, ``.md``) - may be empty if no source file exists
 - ``{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 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.
+   Note that ``_sources`` is still needed for ``llms-full.txt`` at this time.
+
 .. _integration_examples:
 
 Integration Examples

docs/source/conf.py

@@ -15,13 +15,18 @@ import subprocess
 project = "sphinx-llms-txt"
 copyright = "Jared Dillard"
 author = "Jared Dillard"
+
 llms_txt_uri_template = "{base_url}{docname}.md"
+llms_txt_full_file = False
 llms_txt_code_files = ["+:../../sphinx_llms_txt/*.py"]
 llms_txt_summary = """
 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 +55,8 @@ extensions = [
     "sphinx.ext.intersphinx",
     "sphinx_contributors",
     "sphinx_llms_txt",
+    "sphinxcontrib.restbuilder",
+    "sphinx_inline_tabs",
 ]
 
 # The language for content autogenerated by Sphinx. Refer to documentation

docs/source/getting-started.rst

@@ -4,15 +4,17 @@ Getting Started
 Installation
 ------------
 
-Directly install via ``pip`` by using:
+Directly install by using:
 
-.. code-block:: bash
+.. tab:: via pip
+
+   .. code-block:: bash
 
       pip install sphinx-llms-txt
 
-Or with ``conda`` via ``conda-forge``:
+.. tab:: via conda:
 
-.. code::
+   .. code-block:: bash
 
       conda install -c conda-forge sphinx-llms-txt