[docs] Improve docs wording (#59)

docs/source/advanced-configuration.rst

@@ -303,9 +303,11 @@ CMake Workflow
 ^^^^^^^^^^^^^^
 
 This project uses CMake to orchestrate documentation builds across multiple output formats, serving as a simple demo of the functionality.
-Building multiple formats allows you to compare what works best for your docs, as well as allows users to choose which format to feed to their LLM.
 This approach enables parallel builds and integrates well with CI/CD platforms like Read the Docs.
 
+Building multiple formats allows you to compare what works best for your docs, as well as allows users to choose which format to feed to their LLM.
+Use :confval:`llms_txt_uri_template` to configure links to point to your preferred format.
+
 Key Files
 ~~~~~~~~~
 

docs/source/getting-started.rst

@@ -37,8 +37,8 @@ After the HTML finishes building, **sphinx-llms-txt** will output the location o
 Choosing an Output Format
 -------------------------
 
-By default, **sphinx-llms-txt** requires no additional configuration and links to raw reStructuredText source files in :confval:`_sources/ <sphinx:html_copy_source>`.
+By default, **sphinx-llms-txt** requires no additional configuration and links to raw reStructuredText source files created by the HTML builder.
-For optimal LLM support, you can use `sphinx-markdown-builder`_ and/or `sphinxcontrib-restbuilder`_, set up in parallel builds using :ref:`CMake <cmake_workflow>`.
+For optimal LLM support, see the alternative builders below and the :ref:`CMake workflow <cmake_workflow>` for setup.
 
 .. list-table:: Output Format Comparison
    :header-rows: 1
@@ -48,10 +48,14 @@ For optimal LLM support, you can use `sphinx-markdown-builder`_ and/or `sphinxco
      - Default (no config)
      - Markdown (CMake)
      - RST (CMake)
+   * - **Builder**
+     - Native [#native]_
+     - `sphinx-markdown-builder`_
+     - `sphinxcontrib-restbuilder`_
    * - **Format**
      - Raw RST source
-     - Rendered Markdown
+     - Rendered Markdown [#rendered]_
-     - Rendered RST
+     - Rendered RST [#rendered]_
    * - **LLM Readability**
      - Good - preserves structure for simple syntax
      - Excellent - native LLM format
@@ -61,18 +65,21 @@ For optimal LLM support, you can use `sphinx-markdown-builder`_ and/or `sphinxco
      - More compact (less input tokens)
      - Can preserve Sphinx semantics
    * - **Key Disadvantage**
-     - Raw directives (e.g., autodoc) won't be parsed
+     - Raw directives won't be parsed [#autodoc]_
      - Loses structure from complex directives
      - Can lose structure from complex directives
    * - **llms-full.txt support**
-     - Suported with above caveats
+     - Supported with above caveats
-     - Pending `support <https://github.com/liran-funaro/sphinx-markdown-builder/pull/37>`__
+     - Pending `support <https://github.com/liran-funaro/sphinx-markdown-builder/pull/37>`__ [#pending]_
-     - Pending `support <https://github.com/sphinx-contrib/restbuilder/pull/35>`__
+     - Pending `support <https://github.com/sphinx-contrib/restbuilder/pull/35>`__ [#pending]_
-
-
-See :ref:`cmake_workflow` for an example of building HTML, Markdown, and RST in parallel.
-Use :confval:`llms_txt_uri_template` to configure links to point to your preferred format.
 
 .. _sphinx-markdown-builder: https://pypi.org/project/sphinx-markdown-builder/
 .. _sphinxcontrib-restbuilder: https://pypi.org/project/sphinxcontrib-restbuilder/
 
+.. rubric:: Footnotes
+
+.. [#native] Uses raw :confval:`_sources/ <sphinx:html_copy_source>` files created by Sphinx's HTML builder with some minor enhancements.
+.. [#autodoc] Directives like ``autodoc`` will appear as raw directive syntax rather than the extracted docstrings.
+.. [#pending] PRs that add ``llms-full.txt`` concatenation support have yet to be released.
+.. [#rendered] Directives are expanded and processed before output, so content like autodoc docstrings will be included.
+