diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..c435ec6 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = SphinxLLMsTxt +SOURCEDIR = source +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..46bcbbc --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,6 @@ +furo +esbonio +sphinx-contributors +sphinx +-e ../../sphinx-llms-txt +sphinxext-opengraph diff --git a/docs/source/changelog.rst b/docs/source/changelog.rst new file mode 100644 index 0000000..09929fe --- /dev/null +++ b/docs/source/changelog.rst @@ -0,0 +1 @@ +.. include:: ../../CHANGELOG.rst diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..1195b2b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,101 @@ +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +import re +import subprocess + +# -- Project information ----------------------------------------------------- + +project = "Sphinx llms.txt Generator" +copyright = "Jared Dillard" +author = "Jared Dillard" +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. +""" + +# 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"]) + current_tag = GIT_TAG_OUTPUT.decode().strip() + if re.match(r"^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$", current_tag): + version = current_tag + else: + version = "latest" +except (subprocess.CalledProcessError, FileNotFoundError): + version = "latest" + +# The full version, including alpha/beta/rc tags +release = "" + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.intersphinx", + "sphinx_contributors", + "sphinx_llms_txt", +] + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = "en" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +intersphinx_mapping = { + "sphinx": ("https://www.sphinx-doc.org/en/master/", None), +} + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "furo" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +html_theme_options = {} + +html_baseurl = "https://sphinx-llms-txt.readthedocs.org/" + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = "SphinxLLMsTxtdoc" + + +def setup(app): + app.add_object_type( + "confval", + "confval", + objname="configuration value", + indextemplate="pair: %s; configuration value", + ) diff --git a/docs/source/configuration-values.rst b/docs/source/configuration-values.rst new file mode 100644 index 0000000..9b268ec --- /dev/null +++ b/docs/source/configuration-values.rst @@ -0,0 +1,83 @@ +Project Configuration Values +============================ + +.. confval:: llms_txt_full_file + + - **Type**: boolean + - **Default**: ``True`` + - **Description**: Whether to write the single output file + + .. versionadded:: 0.1.0 + +.. confval:: llms_txt_full_filename + + - **Type**: string + - **Default**: ``'llms-full.txt'`` + - **Description**: Name of the single output file + + .. versionadded:: 0.1.0 + +.. confval:: llms_txt_full_max_size + + - **Type**: integer or ``None`` + - **Default**: ``None`` (no limit) + - **Description**: Sets a maximum line count for ``llms_txt_full_filename``. + If exceeded, the file is skipped and a warning is shown, but the build still completes. + + .. versionadded:: 0.2.0 + +.. confval:: llms_txt_file + + - **Type**: boolean + - **Default**: ``True`` + - **Description**: Whether to write the summary information file + + .. versionadded:: 0.2.0 + +.. confval:: llms_txt_filename + + - **Type**: string + - **Default**: ``llms.txt`` + - **Description**: Name of the summary information file + + .. versionadded:: 0.2.0 + +.. confval:: llms_txt_directives + + - **Type**: list of strings + - **Default**: ``[]`` (empty list) + - **Description**: List of custom directive names to process for path resolution. + + .. versionadded:: 0.1.0 + +.. confval:: llms_txt_title + + - **Type**: string or ``None`` + - **Default**: ``None`` + - **Description**: Overrides the Sphinx project name as the heading in ``llms.txt``. + + .. versionadded:: 0.2.0 + +.. confval:: llms_txt_summary + + - **Type**: string or ``None`` + - **Default**: ``None`` + - **Description**: Optional, but recommended, summary description for ``llms.txt``. + + .. versionadded:: 0.2.0 + +.. confval:: llms_txt_exclude + + - **Type**: list of strings + - **Default**: ``[]`` + - **Description**: A list of pages to ignore (e.g., ``["page1", "page_with_*"]``). + + .. versionadded:: 0.2.1 + +.. confval:: llms_txt_rm_directives + + - **Type**: boolean + - **Default**: ``False`` + - **Description**: Whether to remove all directives from the output files. + + .. versionadded:: 0.2.3 diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 0000000..44baf89 --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1,48 @@ +Contributing +============ + +You will need to set up a development environment to make and test your changes before submitting them. + +Local development +----------------- + +#. Clone the `sphinx-llms-txt repository`_. + +#. Create and activate a virtual environment: + + .. code-block:: console + + python3 -m venv .venv + source .venv/bin/activate + +#. Install development dependencies: + + .. code-block:: console + + pip install -e ".[dev]" + +#. Install pre-commit Git hook scripts: + + .. code-block:: console + + pre-commit install + +Testing changes +--------------- + +Run ``pytest`` before committing changes. + +Current contributors +-------------------- + +Thanks to all who have contributed! +The people that have improved the code: + +.. contributors:: jdillard/sphinx-llms-txt + :avatars: + :limit: 100 + :exclude: pre-commit-ci[bot],dependabot[bot] + :order: ASC + + +.. _sphinx-llms-txt repository: https://github.com/jdillard/sphinx-llms-txt diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst new file mode 100644 index 0000000..c88a055 --- /dev/null +++ b/docs/source/getting-started.rst @@ -0,0 +1,24 @@ +Getting Started +=============== + +Installation +------------ + +Directly install via ``pip`` by using: + +.. code-block:: bash + + pip install sphinx-llms-txt + +Usage +----- + +Add the extension to your Sphinx configuration (``conf.py``): + +.. code-block:: python + + extensions = [ + 'sphinx_llms_txt', + ] + +Once added, the extension will automatically generate the LLMs.txt files during the build process. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..8fa8a43 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,33 @@ +Sphinx llms.txt Generator +========================= + +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. + +|PyPI version| + +.. toctree:: + :maxdepth: 2 + + getting-started + configuration-values + contributing + changelog + +Features +-------- + +Sphinx LLMs.txt provides the following features: + +- Creates ``llms.txt`` and ``llms-full.txt`` +- Automatically add content from ``include`` directives +- Resolves relative paths in directives like ``image`` and ``figure`` to use full paths + - Ability to add list of custom directives with ``llms_txt_directives`` + - Optionally, prepend a base URL using Sphinx's ``html_baseurl`` +- Ability to exclude pages + + +.. _Sphinx: http://sphinx-doc.org/ + +.. |PyPI version| image:: https://img.shields.io/pypi/v/sphinx-llms-txt.svg + :target: https://pypi.python.org/pypi/sphinx-llms-txt + :alt: Latest PyPi Version diff --git a/readthedocs.yml b/readthedocs.yml new file mode 100644 index 0000000..eea5bd6 --- /dev/null +++ b/readthedocs.yml @@ -0,0 +1,15 @@ +version: 2 + +build: + os: "ubuntu-20.04" + tools: + python: "3.10" + +sphinx: + configuration: docs/source/conf.py + +python: + install: + - requirements: docs/requirements.txt + - method: pip + path: .