Improve _sources directory handling (#47)

Bumps the all-github-actions group with 2 updates: [actions/checkout](https://github.com/actions/checkout) and [actions/setup-python](https://github.com/actions/setup-python).


Updates `actions/checkout` from 4 to 5
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v4...v5)

Updates `actions/setup-python` from 5 to 6
- [Release notes](https://github.com/actions/setup-python/releases)
- [Commits](https://github.com/actions/setup-python/compare/v5...v6)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-version: '5'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: all-github-actions
- dependency-name: actions/setup-python
  dependency-version: '6'
  dependency-type: direct:production
  update-type: version-update:semver-major
  dependency-group: all-github-actions
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/workflows/test.yml

@@ -10,9 +10,9 @@ jobs:
   pre-commit:
       runs-on: ubuntu-latest
       steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Set up Python 3.10
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.10"
       - uses: pre-commit/action@v3.0.1
@@ -23,17 +23,17 @@ jobs:
         python-version: ['3.9', '3.10', '3.11', '3.12']
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v5
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
 
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e ".[dev]"
+        pip install -e . --group dev
 
     # - name: Run mypy
     #   run: |

CHANGELOG.rst

@@ -1,6 +1,30 @@
 Changelog
 =========
 
+0.6.0
+-----
+
+- Improve _sources directory handling
+  `#47 <https://github.com/jdillard/sphinx-llms-txt/pull/47>`_
+
+0.5.3
+-----
+
+- Make sphinx a required dependency since there are imports from Sphinx
+  `#44 <https://github.com/jdillard/sphinx-llms-txt/pull/44>`_
+
+0.5.2
+-----
+
+- Remove support for singlehtml
+  `#40 <https://github.com/jdillard/sphinx-llms-txt/pull/40>`_
+
+0.5.1
+-----
+
+- Only allow builders that have _sources directory
+  `#38 <https://github.com/jdillard/sphinx-llms-txt/pull/38>`_
+
 0.5.0
 -----
 

README.md

@@ -11,6 +11,10 @@ A Sphinx extension that generates a summary `llms.txt` file and a single combine
 
 See [sphinx-llms-txt documentation](https://sphinx-llms-txt.readthedocs.io/en/latest/index.html) for installation and configuration instructions.
 
+## Contributing
+
+Pull Requests welcome! See [Contributing](https://sphinx-llms-txt.readthedocs.io/en/latest/contributing.html) for instructions on how best to contribute.
+
 ## License
 
 MIT License - see LICENSE file for details.

docs/source/contributing.rst

@@ -19,7 +19,7 @@ Local development
 
    .. code-block:: console
 
-      pip install -e ".[dev]"
+      pip install -e . --group dev
 
 #. Install pre-commit Git hook scripts:
 

pyproject.toml

@@ -26,13 +26,16 @@ classifiers = [
 license = {text = "MIT"}
 readme = "README.md"
 dynamic = ["version"]
+dependencies = [
+    "sphinx",
+]
 
 [project.urls]
 download = "https://pypi.org/project/sphinx-llms-txt/"
 source = "https://github.com/jdillard/sphinx-llms-txt"
 changelog = "https://github.com/jdillard/sphinx-llms-txt/blob/master/CHANGELOG.rst"
 
-[project.optional-dependencies]
+[dependency-groups]
 dev = [
     "pytest>=7.0.0",
     "black",
@@ -40,7 +43,6 @@ dev = [
     "mypy",
     "isort",
     "pre-commit",
-    "sphinx",
 ]
 test = [
     "pytest>=7.0.0",

sphinx_llms_txt/__init__.py

@@ -1,5 +1,14 @@
 """
-Sphinx extension to create a combined sources file (llms-full.txt)
+Sphinx extension that generates llms.txt and llms-full.txt files for LLM consumption.
+
+This extension collects documentation content from Sphinx projects and generates
+two output files:
+- llms.txt: A concise Markdown summary with project overview and page links
+- llms-full.txt: A comprehensive reStructuredText file containing all documentation
+  content with resolved includes and path references
+
+The extension processes content during the build phase, handles page-level and
+block-level ignore directives, and can optionally include source code files.
 """
 
 from typing import Any, Dict
@@ -12,7 +21,7 @@ from .manager import LLMSFullManager
 from .processor import DocumentProcessor
 from .writer import FileWriter
 
-__version__ = "0.5.0"
+__version__ = "0.6.0"
 
 # Export classes needed by tests
 __all__ = [
@@ -104,7 +113,6 @@ def build_finished(app: Sphinx, exception):
 def setup(app: Sphinx) -> Dict[str, Any]:
     """Set up the Sphinx extension."""
 
-    # Add configuration options
     app.add_config_value("llms_txt_file", True, "env")
     app.add_config_value("llms_txt_filename", "llms.txt", "env")
     app.add_config_value("llms_txt_full_file", True, "env")
@@ -118,14 +126,20 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value("llms_txt_code_files", [], "env")
     app.add_config_value("llms_txt_code_base_path", None, "env")
 
-    # Connect to Sphinx events
-    app.connect("doctree-resolved", doctree_resolved)
-    app.connect("build-finished", build_finished)
+    def builder_inited(app):
+        """Used to limit what builders are allowed to run the extension."""
 
-    # Reset manager and root paragraph for each build
-    global _manager, _root_first_paragraph
-    _manager = LLMSFullManager()
-    _root_first_paragraph = ""
+        allowed_builders = ["html", "dirhtml"]
+        if hasattr(app, "builder") and app.builder.name in allowed_builders:
+            # Reset manager and root paragraph for each build
+            global _manager, _root_first_paragraph
+            _manager = LLMSFullManager()
+            _root_first_paragraph = ""
+
+            app.connect("doctree-resolved", doctree_resolved)
+            app.connect("build-finished", build_finished)
+
+    app.connect("builder-inited", builder_inited)
 
     return {
         "version": __version__,

sphinx_llms_txt/manager.py

@@ -197,7 +197,6 @@ class LLMSFullManager:
         possible_sources = [
             Path(outdir) / "_sources",
             Path(outdir) / "html" / "_sources",
-            Path(outdir) / "singlehtml" / "_sources",
         ]
 
         for path in possible_sources:
@@ -205,25 +204,42 @@ class LLMSFullManager:
                 sources_dir = path
                 break
 
-        if not sources_dir:
-            logger.warning(
-                "Could not find _sources directory, skipping llms-full creation"
-            )
-            return
-
-        # Get the correct page order with source suffixes
+        # Get the correct page order (with or without source suffixes)
         page_order = self.collector.get_page_order(sources_dir)
 
         if not page_order:
-            logger.warning(
-                "Could not determine page order, skipping llms-full creation"
-            )
+            logger.warning("Could not determine page order, skipping file generation")
             return
 
         # Apply exclusion filter if configured
         page_order = self.collector.filter_excluded_pages(page_order)
 
-        # Determine output file name and location
+        # If no sources directory, only generate llms.txt and return early
+        if not sources_dir:
+            # Generate llms.txt if requested
+            if self.config.get("llms_txt_file"):
+                filtered_page_order = self._filter_ignored_pages(page_order)
+                self.writer.write_verbose_info_to_file(
+                    filtered_page_order,
+                    self.collector.page_titles,
+                    0,  # No line count since no llms-full.txt
+                )
+
+            # Only warn if user explicitly wants llms-full.txt
+            if self.config.get("llms_txt_full_file"):
+                # Check if html_copy_source is False
+                if self.app and not self.app.config.html_copy_source:
+                    logger.warning(
+                        "Could not find _sources directory, skipping llms-full.txt."
+                        "Set html_copy_source = True in conf.py to enable."
+                    )
+                else:
+                    logger.warning(
+                        "Could not find _sources directory, skipping llms-full.txt"
+                    )
+            return
+
+        # Determine output file name and location for llms-full.txt
         output_filename = self.config.get("llms_txt_full_filename")
         output_path = Path(outdir) / output_filename
 

tests/test_llms_txt.py

@@ -41,6 +41,42 @@ def test_setup_returns_valid_dict():
     assert "parallel_write_safe" in result
 
 
+def test_builder_inited_with_disallowed_builder():
+    """Test that disallowed builders do not trigger extension setup."""
+    import sphinx_llms_txt
+
+    # Reset global state
+    sphinx_llms_txt._manager = sphinx_llms_txt.LLMSFullManager()
+    sphinx_llms_txt._root_first_paragraph = ""
+
+    # Mock a Sphinx app with a disallowed builder
+    class MockBuilder:
+        name = "text"  # Not in allowed list
+
+    class MockApp:
+        def __init__(self):
+            self.config_values = {}
+            self.connections = {}
+            self.builder = MockBuilder()
+
+        def add_config_value(self, name, default, rebuild):
+            self.config_values[name] = (default, rebuild)
+
+        def connect(self, event, handler):
+            self.connections[event] = handler
+
+    app = MockApp()
+    setup(app)
+
+    # Trigger builder-inited
+    builder_inited_handler = app.connections["builder-inited"]
+    builder_inited_handler(app)
+
+    # With disallowed builder, other events should NOT be connected
+    assert "doctree-resolved" not in app.connections
+    assert "build-finished" not in app.connections
+
+
 def test_document_collector_initialization():
     """Test initialization of DocumentCollector."""
     collector = DocumentCollector()
@@ -995,3 +1031,128 @@ def test_code_files_ignored_patterns(tmp_path, caplog):
     assert (
         "Code file pattern 'docs/**/*.rst' ignored." in captured_warnings[0]
     ), f"Warning message should contain expected text. Got: {captured_warnings[0]}"
+
+
+def test_llms_txt_generated_without_sources_dir(tmp_path):
+    """Test that llms.txt is generated even when _sources directory doesn't exist."""
+
+    from sphinx_llms_txt.manager import LLMSFullManager
+
+    # Create manager
+    manager = LLMSFullManager()
+
+    # Set config to enable llms.txt
+    config = {
+        "llms_txt_file": True,
+        "llms_txt_filename": "llms.txt",
+        "llms_txt_full_file": True,
+        "llms_txt_full_filename": "llms-full.txt",
+        "llms_txt_exclude": [],
+        "llms_txt_directives": [],
+    }
+    manager.set_config(config)
+
+    # Create directories (but no _sources)
+    outdir = tmp_path / "build"
+    srcdir = tmp_path / "source"
+    outdir.mkdir()
+    srcdir.mkdir()
+
+    # Mock env with documents
+    class MockEnv:
+        all_docs = {"index": None, "about": None}
+        titles = {
+            "index": type("TitleNode", (), {"astext": lambda self: "Home"})(),
+            "about": type("TitleNode", (), {"astext": lambda self: "About"})(),
+        }
+        toctree_includes = {"index": ["about"]}
+
+    manager.set_env(MockEnv())
+    manager.set_master_doc("index")
+
+    # Update page titles directly in the collector
+    manager.update_page_title("index", "Home")
+    manager.update_page_title("about", "About")
+
+    # Call combine_sources - should generate llms.txt even without _sources
+    manager.combine_sources(str(outdir), str(srcdir))
+
+    # Verify llms.txt was created
+    llms_txt = outdir / "llms.txt"
+    assert llms_txt.exists(), "llms.txt should be generated even without _sources"
+
+    # Verify llms-full.txt was NOT created (since no _sources)
+    llms_full_txt = outdir / "llms-full.txt"
+    assert (
+        not llms_full_txt.exists()
+    ), "llms-full.txt should not be generated without _sources"
+
+    # Read llms.txt and verify it has content
+    with open(llms_txt, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    # Should contain page titles and links
+    assert "Home" in content
+    assert "About" in content
+    assert "index.html" in content
+    assert "about.html" in content
+
+
+def test_llms_txt_no_warning_when_full_file_disabled(tmp_path, caplog):
+    """
+    Test that no warning is logged when llms_txt_full_file=False and
+    _sources doesn't exist.
+    """
+    from unittest.mock import patch
+
+    from sphinx_llms_txt.manager import LLMSFullManager
+
+    # Create manager
+    manager = LLMSFullManager()
+
+    # Set config with llms_txt_full_file=False
+    config = {
+        "llms_txt_file": True,
+        "llms_txt_filename": "llms.txt",
+        "llms_txt_full_file": False,  # User doesn't want llms-full.txt
+        "llms_txt_full_filename": "llms-full.txt",
+        "llms_txt_exclude": [],
+        "llms_txt_directives": [],
+    }
+    manager.set_config(config)
+
+    # Create directories (but no _sources)
+    outdir = tmp_path / "build"
+    srcdir = tmp_path / "source"
+    outdir.mkdir()
+    srcdir.mkdir()
+
+    # Mock env with documents
+    class MockEnv:
+        all_docs = {"index": None}
+        titles = {"index": type("TitleNode", (), {"astext": lambda self: "Home"})()}
+        toctree_includes = {"index": []}
+
+    manager.set_env(MockEnv())
+    manager.set_master_doc("index")
+    manager.update_page_title("index", "Home")
+
+    # Capture warnings
+    captured_warnings = []
+
+    def capture_warning(message, *args, **kwargs):
+        if "_sources" in str(message):
+            captured_warnings.append(message)
+
+    with patch("sphinx_llms_txt.manager.logger.warning", side_effect=capture_warning):
+        # Call combine_sources
+        manager.combine_sources(str(outdir), str(srcdir))
+
+    # Verify NO warning was logged since llms_txt_full_file=False
+    assert (
+        len(captured_warnings) == 0
+    ), "No warning should be logged when llms_txt_full_file=False"
+
+    # Verify llms.txt was still created
+    llms_txt = outdir / "llms.txt"
+    assert llms_txt.exists()