diff --git a/CMakeLists.txt b/CMakeLists.txt index 3f5e3c3..9f0ba42 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,8 +1,15 @@ cmake_minimum_required(VERSION 3.15) project(SphinxLLMsTxt VERSION 1.0.0 LANGUAGES NONE) -# Add CMake module path -list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake") +# Fetch Sphinx CMake modules +include(FetchContent) +FetchContent_Declare( + sphinx_cmake_modules + GIT_REPOSITORY https://github.com/jdillard/sphinx-cmake-modules.git + GIT_TAG main +) +FetchContent_MakeAvailable(sphinx_cmake_modules) +list(APPEND CMAKE_MODULE_PATH "${sphinx_cmake_modules_SOURCE_DIR}") # Add documentation add_subdirectory(docs) diff --git a/CMakePresets.json b/CMakePresets.json index 1336542..24b5152 100644 --- a/CMakePresets.json +++ b/CMakePresets.json @@ -29,7 +29,7 @@ }, { "name": "docs-parallel", - "displayName": "Build HTML and Markdown in parallel", + "displayName": "Build all output formats in parallel", "configurePreset": "documentation", "targets": ["html", "markdown", "rst"] } diff --git a/cmake/SphinxUtils.cmake b/cmake/SphinxUtils.cmake deleted file mode 100644 index 2277f66..0000000 --- a/cmake/SphinxUtils.cmake +++ /dev/null @@ -1,28 +0,0 @@ -# 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) - # Find sphinx-build executable in system - find_program(SPHINX_EXECUTABLE - NAMES sphinx-build - DOC "Sphinx documentation generator" - ) - - if(NOT SPHINX_EXECUTABLE) - message(FATAL_ERROR "sphinx-build not found. Please install Sphinx.") - endif() - - # 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/requirements.txt b/docs/requirements.txt index 956bae7..496c26e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,6 +2,7 @@ furo esbonio sphinx-contributors sphinx +sphinx-design sphinx-llms-txt sphinx-inline-tabs sphinxext-opengraph diff --git a/docs/source/advanced-configuration.rst b/docs/source/advanced-configuration.rst index a6097c2..18c27d0 100644 --- a/docs/source/advanced-configuration.rst +++ b/docs/source/advanced-configuration.rst @@ -311,36 +311,113 @@ Use :confval:`llms_txt_uri_template` to configure links to point to your preferr Key Files ~~~~~~~~~ +These configuration files serve as a simple example of a Sphinx site hosted on Read The Docs, some modification may be needed. + .. code-block:: text . ├── .readthedocs.yml ├── CMakeLists.txt ├── CMakePresets.json - ├── cmake/ - │ └── SphinxUtils.cmake └── docs/ └── CMakeLists.txt -:ghfile:`.readthedocs.yml` +Each section below contains a summary of the file's purpose, the full contents of the file, and a table describing key lines that may need modification. + +.. dropdown:: .readthedocs.yml + :chevron: down-up + 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. + .. literalinclude:: ../../.readthedocs.yml + :language: yaml + :lines: 1-9,11,14- + :linenos: + :emphasize-lines: 9, 14-15 -:ghfile:`docs/CMakeLists.txt` - A CMake config file that includes the Sphinx utilities and defines the documentation-specific build targets. + .. list-table:: + :header-rows: 1 + :width: 100% + :widths: 15 85 -:ghfile:`cmake/SphinxUtils.cmake` - A CMake module that provides Sphinx related utilities. + * - Line + - Description + * - **9** + - Update the path if your requirements file is in a different location + * - **13-14** + - Modify the copy commands for the output formats you deploy + +.. dropdown:: CMakeLists.txt + :chevron: down-up + + A CMake config file that sets up the project, fetches the shared `sphinx-cmake-modules `_, and includes the docs subdirectory. + + .. literalinclude:: ../../CMakeLists.txt + :language: cmake + :linenos: + :emphasize-lines: 9, 15 + + .. list-table:: + :header-rows: 1 + :width: 100% + :widths: 15 85 + + * - Line + - Description + * - **9** + - Update the ``GIT_TAG`` to use a different version or commit hash + * - **15** + - Change if your docs subdirectory has a different location + +.. dropdown:: docs/CMakeLists.txt + :chevron: down-up + + A CMake config file that includes the `SphinxUtils `_ module from FetchContent and defines the documentation-specific build targets. + + .. literalinclude:: ../CMakeLists.txt + :language: cmake + :linenos: + :emphasize-lines: 5-7 + + .. list-table:: + :header-rows: 1 + :width: 100% + :widths: 15 85 + + * - Line + - Description + * - **5-7** + - Add or remove calls based on which output formats you need + + +.. dropdown:: CMakePresets.json + :chevron: down-up -: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. + - **Build Presets:** Defines build formats individually and all in parallel. - **Workflow Presets:** Runs the configure preset followed by the parallel build preset. + .. literalinclude:: ../../CMakePresets.json + :language: json + :linenos: + :emphasize-lines: 18-23, 24-29, 34 + + .. list-table:: + :header-rows: 1 + :width: 100% + :widths: 15 85 + + * - Line + - Description + * - **18-23** + - Remove this preset to disable Markdown documentation builds + * - **24-29** + - Remove this preset to disable reStructuredText documentation builds + * - **34** + - Modify the targets list to build only the output formats you need in parallel + Usage ~~~~~ diff --git a/docs/source/conf.py b/docs/source/conf.py index 5a4185f..49a26e5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -26,10 +26,6 @@ and a single combined documentation llms-full.txt file, written in reStructuredT # rst_file_suffix = ".html.rst" markdown_file_suffix = ".html.md" -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"]) @@ -61,6 +57,7 @@ extensions = [ "sphinxcontrib.restbuilder", "sphinx_inline_tabs", "sphinx.ext.extlinks", + "sphinx_design", ] # The language for content autogenerated by Sphinx. Refer to documentation