From 799eabd8271f196df453d42f6d5954ba89644513 Mon Sep 17 00:00:00 2001 From: Major Hayden Date: Thu, 22 Jan 2026 17:02:14 -0600 Subject: [PATCH 1/5] feat(docs): add mkdocs infrastructure and dependencies Add MkDocs Material framework as foundation for documentation: - Add 'docs' dependency group to pyproject.toml with mkdocs-material, mkdocstrings, and supporting plugins - Create minimal mkdocs.yml configuration with Material theme - Add Makefile targets for building and serving docs locally This establishes the infrastructure for migrating from Jekyll to MkDocs. Content migration and API reference generation will follow. Signed-off-by: Major Hayden --- Makefile | 6 + mkdocs.yml | 50 +++++++++ pyproject.toml | 8 ++ uv.lock | 291 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 355 insertions(+) create mode 100644 mkdocs.yml diff --git a/Makefile b/Makefile index e08944cb5..ffdc9d1d1 100644 --- a/Makefile +++ b/Makefile @@ -67,6 +67,12 @@ requirements.txt: pyproject.toml pdm.lock ## Generate requirements.txt file cont doc: ## Generate documentation for developers scripts/gen_doc.py +docs-build: ## Build MkDocs documentation + uv run mkdocs build + +docs-serve: ## Serve MkDocs documentation locally with hot-reload + uv run mkdocs serve + docs/config.puml: src/models/config.py ## Generate PlantUML class diagram for configuration pyreverse src/models/config.py --output puml --output-directory=docs/ mv docs/classes.puml docs/config.puml diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 000000000..594021070 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,50 @@ +site_name: Lightspeed Core Stack +site_url: https://lightspeed-core.github.io/lightspeed-stack/ +site_description: AI-powered assistant using LLM services, agents, and RAG databases + +repo_name: lightspeed-core/lightspeed-stack +repo_url: https://github.com/lightspeed-core/lightspeed-stack + +docs_dir: docs + +theme: + name: material + features: + - navigation.tabs + - navigation.sections + - navigation.top + - search.highlight + - content.code.copy + palette: + - scheme: default + primary: red + accent: red + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - scheme: slate + primary: red + accent: red + toggle: + icon: material/brightness-4 + name: Switch to light mode + logo: logo.jpg + favicon: logo.jpg + +plugins: + - search + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - admonition + - pymdownx.details + - toc: + permalink: true + +# Minimal nav for infrastructure PR - will be expanded in PR 2 +nav: + - Home: index.md diff --git a/pyproject.toml b/pyproject.toml index f231db5a9..eda8b5f55 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -190,6 +190,14 @@ build = [ "twine>=6.1.0", ] +docs = [ + "mkdocs-material>=9.6", + "mkdocstrings[python]>=0.27", + "mkdocs-gen-files>=0.5", + "mkdocs-literate-nav>=0.6", + "mkdocs-section-index>=0.3", +] + [tool.pytest.ini_options] asyncio_mode = "auto" pythonpath = [ diff --git a/uv.lock b/uv.lock index c5e179387..f17e8951b 100644 --- a/uv.lock +++ b/uv.lock @@ -254,6 +254,28 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/83/7b/5652771e24fff12da9dde4c20ecf4682e606b104f26419d139758cc935a6/azure_identity-1.25.1-py3-none-any.whl", hash = "sha256:e9edd720af03dff020223cd269fa3a61e8f345ea75443858273bcb44844ab651", size = 191317, upload-time = "2025-10-06T20:30:04.251Z" }, ] +[[package]] +name = "babel" +version = "2.17.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/7d/6b/d52e42361e1aa00709585ecc30b3f9684b3ab62530771402248b1b1d6240/babel-2.17.0.tar.gz", hash = "sha256:0c54cffb19f690cdcc52a3b50bcbf71e07a808d1c80d549f2459b9d2cf0afb9d", size = 9951852, upload-time = "2025-02-01T15:17:41.026Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/b7/b8/3fe70c75fe32afc4bb507f75563d39bc5642255d1d94f1f23604725780bf/babel-2.17.0-py3-none-any.whl", hash = "sha256:4d0b53093fdfb4b21c92b5213dba5a1b23885afa8383709427046b21c366e5f2", size = 10182537, upload-time = "2025-02-01T15:17:37.39Z" }, +] + +[[package]] +name = "backrefs" +version = "6.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/86/e3/bb3a439d5cb255c4774724810ad8073830fac9c9dee123555820c1bcc806/backrefs-6.1.tar.gz", hash = "sha256:3bba1749aafe1db9b915f00e0dd166cba613b6f788ffd63060ac3485dc9be231", size = 7011962, upload-time = "2025-11-15T14:52:08.323Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/3b/ee/c216d52f58ea75b5e1841022bbae24438b19834a29b163cb32aa3a2a7c6e/backrefs-6.1-py310-none-any.whl", hash = "sha256:2a2ccb96302337ce61ee4717ceacfbf26ba4efb1d55af86564b8bbaeda39cac1", size = 381059, upload-time = "2025-11-15T14:51:59.758Z" }, + { url = "https://files.pythonhosted.org/packages/e6/9a/8da246d988ded941da96c7ed945d63e94a445637eaad985a0ed88787cb89/backrefs-6.1-py311-none-any.whl", hash = "sha256:e82bba3875ee4430f4de4b6db19429a27275d95a5f3773c57e9e18abc23fd2b7", size = 392854, upload-time = "2025-11-15T14:52:01.194Z" }, + { url = "https://files.pythonhosted.org/packages/37/c9/fd117a6f9300c62bbc33bc337fd2b3c6bfe28b6e9701de336b52d7a797ad/backrefs-6.1-py312-none-any.whl", hash = "sha256:c64698c8d2269343d88947c0735cb4b78745bd3ba590e10313fbf3f78c34da5a", size = 398770, upload-time = "2025-11-15T14:52:02.584Z" }, + { url = "https://files.pythonhosted.org/packages/eb/95/7118e935b0b0bd3f94dfec2d852fd4e4f4f9757bdb49850519acd245cd3a/backrefs-6.1-py313-none-any.whl", hash = "sha256:4c9d3dc1e2e558965202c012304f33d4e0e477e1c103663fd2c3cc9bb18b0d05", size = 400726, upload-time = "2025-11-15T14:52:04.093Z" }, + { url = "https://files.pythonhosted.org/packages/02/e3/a4fa1946722c4c7b063cc25043a12d9ce9b4323777f89643be74cef2993c/backrefs-6.1-py39-none-any.whl", hash = "sha256:a9e99b8a4867852cad177a6430e31b0f6e495d65f8c6c134b68c14c3c95bf4b0", size = 381058, upload-time = "2025-11-15T14:52:06.698Z" }, +] + [[package]] name = "bandit" version = "1.9.2" @@ -832,6 +854,18 @@ http = [ { name = "aiohttp" }, ] +[[package]] +name = "ghp-import" +version = "2.1.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "python-dateutil" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/d9/29/d40217cbe2f6b1359e00c6c307bb3fc876ba74068cbab3dde77f03ca0dc4/ghp-import-2.1.0.tar.gz", hash = "sha256:9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343", size = 10943, upload-time = "2022-05-02T15:47:16.11Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/f7/ec/67fbef5d497f86283db54c22eec6f6140243aae73265799baaaa19cd17fb/ghp_import-2.1.0-py3-none-any.whl", hash = "sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619", size = 11034, upload-time = "2022-05-02T15:47:14.552Z" }, +] + [[package]] name = "google-api-core" version = "2.29.0" @@ -897,6 +931,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/7e/71/ba21c3fb8c5dce83b8c01f458a42e99ffdb1963aeec08fff5a18588d8fd7/greenlet-3.3.0-cp313-cp313-win_amd64.whl", hash = "sha256:9ee1942ea19550094033c35d25d20726e4f1c40d59545815e1128ac58d416d38", size = 301833, upload-time = "2025-12-04T14:32:23.929Z" }, ] +[[package]] +name = "griffe" +version = "1.15.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "colorama" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/0d/0c/3a471b6e31951dce2360477420d0a8d1e00dea6cf33b70f3e8c3ab6e28e1/griffe-1.15.0.tar.gz", hash = "sha256:7726e3afd6f298fbc3696e67958803e7ac843c1cfe59734b6251a40cdbfb5eea", size = 424112, upload-time = "2025-11-10T15:03:15.52Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9c/83/3b1d03d36f224edded98e9affd0467630fc09d766c0e56fb1498cbb04a9b/griffe-1.15.0-py3-none-any.whl", hash = "sha256:6f6762661949411031f5fcda9593f586e6ce8340f0ba88921a0f2ef7a81eb9a3", size = 150705, upload-time = "2025-11-10T15:03:13.549Z" }, +] + [[package]] name = "grpcio" version = "1.76.0" @@ -1348,6 +1394,13 @@ dev = [ { name = "types-pyyaml" }, { name = "types-requests" }, ] +docs = [ + { name = "mkdocs-gen-files" }, + { name = "mkdocs-literate-nav" }, + { name = "mkdocs-material" }, + { name = "mkdocs-section-index" }, + { name = "mkdocstrings", extra = ["python"] }, +] llslibdev = [ { name = "aiosqlite" }, { name = "autoevals" }, @@ -1434,6 +1487,13 @@ dev = [ { name = "types-pyyaml", specifier = ">=6.0.2" }, { name = "types-requests", specifier = ">=2.28.0" }, ] +docs = [ + { name = "mkdocs-gen-files", specifier = ">=0.5" }, + { name = "mkdocs-literate-nav", specifier = ">=0.6" }, + { name = "mkdocs-material", specifier = ">=9.6" }, + { name = "mkdocs-section-index", specifier = ">=0.3" }, + { name = "mkdocstrings", extras = ["python"], specifier = ">=0.27" }, +] llslibdev = [ { name = "aiosqlite", specifier = ">=0.21.0" }, { name = "autoevals", specifier = ">=0.0.129" }, @@ -1590,6 +1650,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/31/ef/dcf1d29c3f530577f61e5fe2f1bd72929acf779953668a8a47a479ae6f26/lxml-6.0.2-cp313-cp313-win_arm64.whl", hash = "sha256:13dcecc9946dca97b11b7c40d29fba63b55ab4170d3c0cf8c0c164343b9bfdcf", size = 3671248, upload-time = "2025-09-22T04:02:27.918Z" }, ] +[[package]] +name = "markdown" +version = "3.10.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/b7/b1/af95bcae8549f1f3fd70faacb29075826a0d689a27f232e8cee315efa053/markdown-3.10.1.tar.gz", hash = "sha256:1c19c10bd5c14ac948c53d0d762a04e2fa35a6d58a6b7b1e6bfcbe6fefc0001a", size = 365402, upload-time = "2026-01-21T18:09:28.206Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/59/1b/6ef961f543593969d25b2afe57a3564200280528caa9bd1082eecdd7b3bc/markdown-3.10.1-py3-none-any.whl", hash = "sha256:867d788939fe33e4b736426f5b9f651ad0c0ae0ecf89df0ca5d1176c70812fe3", size = 107684, upload-time = "2026-01-21T18:09:27.203Z" }, +] + [[package]] name = "markdown-it-py" version = "4.0.0" @@ -1686,6 +1755,170 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" }, ] +[[package]] +name = "mergedeep" +version = "1.3.4" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/3a/41/580bb4006e3ed0361b8151a01d324fb03f420815446c7def45d02f74c270/mergedeep-1.3.4.tar.gz", hash = "sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8", size = 4661, upload-time = "2021-02-05T18:55:30.623Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/2c/19/04f9b178c2d8a15b076c8b5140708fa6ffc5601fb6f1e975537072df5b2a/mergedeep-1.3.4-py3-none-any.whl", hash = "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307", size = 6354, upload-time = "2021-02-05T18:55:29.583Z" }, +] + +[[package]] +name = "mkdocs" +version = "1.6.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "click" }, + { name = "colorama", marker = "sys_platform == 'win32'" }, + { name = "ghp-import" }, + { name = "jinja2" }, + { name = "markdown" }, + { name = "markupsafe" }, + { name = "mergedeep" }, + { name = "mkdocs-get-deps" }, + { name = "packaging" }, + { name = "pathspec" }, + { name = "pyyaml" }, + { name = "pyyaml-env-tag" }, + { name = "watchdog" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/bc/c6/bbd4f061bd16b378247f12953ffcb04786a618ce5e904b8c5a01a0309061/mkdocs-1.6.1.tar.gz", hash = "sha256:7b432f01d928c084353ab39c57282f29f92136665bdd6abf7c1ec8d822ef86f2", size = 3889159, upload-time = "2024-08-30T12:24:06.899Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/22/5b/dbc6a8cddc9cfa9c4971d59fb12bb8d42e161b7e7f8cc89e49137c5b279c/mkdocs-1.6.1-py3-none-any.whl", hash = "sha256:db91759624d1647f3f34aa0c3f327dd2601beae39a366d6e064c03468d35c20e", size = 3864451, upload-time = "2024-08-30T12:24:05.054Z" }, +] + +[[package]] +name = "mkdocs-autorefs" +version = "1.4.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markdown" }, + { name = "markupsafe" }, + { name = "mkdocs" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/51/fa/9124cd63d822e2bcbea1450ae68cdc3faf3655c69b455f3a7ed36ce6c628/mkdocs_autorefs-1.4.3.tar.gz", hash = "sha256:beee715b254455c4aa93b6ef3c67579c399ca092259cc41b7d9342573ff1fc75", size = 55425, upload-time = "2025-08-26T14:23:17.223Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9f/4d/7123b6fa2278000688ebd338e2a06d16870aaf9eceae6ba047ea05f92df1/mkdocs_autorefs-1.4.3-py3-none-any.whl", hash = "sha256:469d85eb3114801d08e9cc55d102b3ba65917a869b893403b8987b601cf55dc9", size = 25034, upload-time = "2025-08-26T14:23:15.906Z" }, +] + +[[package]] +name = "mkdocs-gen-files" +version = "0.6.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mkdocs" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/61/35/f26349f7fa18414eb2e25d75a6fa9c7e3186c36e1d227c0b2d785a7bd5c4/mkdocs_gen_files-0.6.0.tar.gz", hash = "sha256:52022dc14dcc0451e05e54a8f5d5e7760351b6701eff816d1e9739577ec5635e", size = 8642, upload-time = "2025-11-23T12:13:22.124Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8d/ec/72417415563c60ae01b36f0d497f1f4c803972f447ef4fb7f7746d6e07db/mkdocs_gen_files-0.6.0-py3-none-any.whl", hash = "sha256:815af15f3e2dbfda379629c1b95c02c8e6f232edf2a901186ea3b204ab1135b2", size = 8182, upload-time = "2025-11-23T12:13:20.756Z" }, +] + +[[package]] +name = "mkdocs-get-deps" +version = "0.2.0" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mergedeep" }, + { name = "platformdirs" }, + { name = "pyyaml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/98/f5/ed29cd50067784976f25ed0ed6fcd3c2ce9eb90650aa3b2796ddf7b6870b/mkdocs_get_deps-0.2.0.tar.gz", hash = "sha256:162b3d129c7fad9b19abfdcb9c1458a651628e4b1dea628ac68790fb3061c60c", size = 10239, upload-time = "2023-11-20T17:51:09.981Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/9f/d4/029f984e8d3f3b6b726bd33cafc473b75e9e44c0f7e80a5b29abc466bdea/mkdocs_get_deps-0.2.0-py3-none-any.whl", hash = "sha256:2bf11d0b133e77a0dd036abeeb06dec8775e46efa526dc70667d8863eefc6134", size = 9521, upload-time = "2023-11-20T17:51:08.587Z" }, +] + +[[package]] +name = "mkdocs-literate-nav" +version = "0.6.2" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mkdocs" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/f6/5f/99aa379b305cd1c2084d42db3d26f6de0ea9bf2cc1d10ed17f61aff35b9a/mkdocs_literate_nav-0.6.2.tar.gz", hash = "sha256:760e1708aa4be86af81a2b56e82c739d5a8388a0eab1517ecfd8e5aa40810a75", size = 17419, upload-time = "2025-03-18T21:53:09.711Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/8a/84/b5b14d2745e4dd1a90115186284e9ee1b4d0863104011ab46abb7355a1c3/mkdocs_literate_nav-0.6.2-py3-none-any.whl", hash = "sha256:0a6489a26ec7598477b56fa112056a5e3a6c15729f0214bea8a4dbc55bd5f630", size = 13261, upload-time = "2025-03-18T21:53:08.1Z" }, +] + +[[package]] +name = "mkdocs-material" +version = "9.7.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "babel" }, + { name = "backrefs" }, + { name = "colorama" }, + { name = "jinja2" }, + { name = "markdown" }, + { name = "mkdocs" }, + { name = "mkdocs-material-extensions" }, + { name = "paginate" }, + { name = "pygments" }, + { name = "pymdown-extensions" }, + { name = "requests" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/27/e2/2ffc356cd72f1473d07c7719d82a8f2cbd261666828614ecb95b12169f41/mkdocs_material-9.7.1.tar.gz", hash = "sha256:89601b8f2c3e6c6ee0a918cc3566cb201d40bf37c3cd3c2067e26fadb8cce2b8", size = 4094392, upload-time = "2025-12-18T09:49:00.308Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/3e/32/ed071cb721aca8c227718cffcf7bd539620e9799bbf2619e90c757bfd030/mkdocs_material-9.7.1-py3-none-any.whl", hash = "sha256:3f6100937d7d731f87f1e3e3b021c97f7239666b9ba1151ab476cabb96c60d5c", size = 9297166, upload-time = "2025-12-18T09:48:56.664Z" }, +] + +[[package]] +name = "mkdocs-material-extensions" +version = "1.3.1" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/79/9b/9b4c96d6593b2a541e1cb8b34899a6d021d208bb357042823d4d2cabdbe7/mkdocs_material_extensions-1.3.1.tar.gz", hash = "sha256:10c9511cea88f568257f960358a467d12b970e1f7b2c0e5fb2bb48cab1928443", size = 11847, upload-time = "2023-11-22T19:09:45.208Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/5b/54/662a4743aa81d9582ee9339d4ffa3c8fd40a4965e033d77b9da9774d3960/mkdocs_material_extensions-1.3.1-py3-none-any.whl", hash = "sha256:adff8b62700b25cb77b53358dad940f3ef973dd6db797907c49e3c2ef3ab4e31", size = 8728, upload-time = "2023-11-22T19:09:43.465Z" }, +] + +[[package]] +name = "mkdocs-section-index" +version = "0.3.10" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "mkdocs" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/93/40/4aa9d3cfa2ac6528b91048847a35f005b97ec293204c02b179762a85b7f2/mkdocs_section_index-0.3.10.tar.gz", hash = "sha256:a82afbda633c82c5568f0e3b008176b9b365bf4bd8b6f919d6eff09ee146b9f8", size = 14446, upload-time = "2025-04-05T20:56:45.387Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/01/53/76c109e6f822a6d19befb0450c87330b9a6ce52353de6a9dda7892060a1f/mkdocs_section_index-0.3.10-py3-none-any.whl", hash = "sha256:bc27c0d0dc497c0ebaee1fc72839362aed77be7318b5ec0c30628f65918e4776", size = 8796, upload-time = "2025-04-05T20:56:43.975Z" }, +] + +[[package]] +name = "mkdocstrings" +version = "1.0.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "jinja2" }, + { name = "markdown" }, + { name = "markupsafe" }, + { name = "mkdocs" }, + { name = "mkdocs-autorefs" }, + { name = "pymdown-extensions" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/bd/ec/680e3bc7c88704d3fb9c658a517ec10f2f2aed3b9340136978675e581688/mkdocstrings-1.0.1.tar.gz", hash = "sha256:caa7d311c85ac0a0674831725ecfdeee4348e3b8a2c91ab193ee319a41dbeb3d", size = 100794, upload-time = "2026-01-19T11:36:24.429Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/d0/f9/ecd3e5cf258d63eddc13e354bd090df3aa458b64be50d737d52a8ad9df22/mkdocstrings-1.0.1-py3-none-any.whl", hash = "sha256:10deb908e310e6d427a5b8f69026361dac06b77de860f46043043e26f121db02", size = 35245, upload-time = "2026-01-19T11:36:23.067Z" }, +] + +[package.optional-dependencies] +python = [ + { name = "mkdocstrings-python" }, +] + +[[package]] +name = "mkdocstrings-python" +version = "2.0.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "griffe" }, + { name = "mkdocs-autorefs" }, + { name = "mkdocstrings" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/24/75/d30af27a2906f00eb90143470272376d728521997800f5dce5b340ba35bc/mkdocstrings_python-2.0.1.tar.gz", hash = "sha256:843a562221e6a471fefdd4b45cc6c22d2607ccbad632879234fa9692e9cf7732", size = 199345, upload-time = "2025-12-03T14:26:11.755Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/81/06/c5f8deba7d2cbdfa7967a716ae801aa9ca5f734b8f54fd473ef77a088dbe/mkdocstrings_python-2.0.1-py3-none-any.whl", hash = "sha256:66ecff45c5f8b71bf174e11d49afc845c2dfc7fc0ab17a86b6b337e0f24d8d90", size = 105055, upload-time = "2025-12-03T14:26:10.184Z" }, +] + [[package]] name = "more-itertools" version = "10.8.0" @@ -2122,6 +2355,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/20/12/38679034af332785aac8774540895e234f4d07f7545804097de4b666afd8/packaging-25.0-py3-none-any.whl", hash = "sha256:29572ef2b1f17581046b3a2227d5c611fb25ec70ca1ba8554b24b0e69331a484", size = 66469, upload-time = "2025-04-19T11:48:57.875Z" }, ] +[[package]] +name = "paginate" +version = "0.5.7" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/ec/46/68dde5b6bc00c1296ec6466ab27dddede6aec9af1b99090e1107091b3b84/paginate-0.5.7.tar.gz", hash = "sha256:22bd083ab41e1a8b4f3690544afb2c60c25e5c9a63a30fa2f483f6c60c8e5945", size = 19252, upload-time = "2024-08-25T14:17:24.139Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/90/96/04b8e52da071d28f5e21a805b19cb9390aa17a47462ac87f5e2696b9566d/paginate-0.5.7-py2.py3-none-any.whl", hash = "sha256:b885e2af73abcf01d9559fd5216b57ef722f8c42affbb63942377668e35c7591", size = 13746, upload-time = "2024-08-25T14:17:22.55Z" }, +] + [[package]] name = "pandas" version = "2.3.3" @@ -2723,6 +2965,19 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/a6/92/d40f5d937517cc489ad848fc4414ecccc7592e4686b9071e09e64f5e378e/pylint-4.0.4-py3-none-any.whl", hash = "sha256:63e06a37d5922555ee2c20963eb42559918c20bd2b21244e4ef426e7c43b92e0", size = 536425, upload-time = "2025-11-30T13:29:02.53Z" }, ] +[[package]] +name = "pymdown-extensions" +version = "10.20" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "markdown" }, + { name = "pyyaml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/3e/35/e3814a5b7df295df69d035cfb8aab78b2967cdf11fcfae7faed726b66664/pymdown_extensions-10.20.tar.gz", hash = "sha256:5c73566ab0cf38c6ba084cb7c5ea64a119ae0500cce754ccb682761dfea13a52", size = 852774, upload-time = "2025-12-31T19:59:42.211Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/ea/10/47caf89cbb52e5bb764696fd52a8c591a2f0e851a93270c05a17f36000b5/pymdown_extensions-10.20-py3-none-any.whl", hash = "sha256:ea9e62add865da80a271d00bfa1c0fa085b20d133fb3fc97afdc88e682f60b2f", size = 268733, upload-time = "2025-12-31T19:59:40.652Z" }, +] + [[package]] name = "pyproject-hooks" version = "1.2.0" @@ -2927,6 +3182,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" }, ] +[[package]] +name = "pyyaml-env-tag" +version = "1.1" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "pyyaml" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/eb/2e/79c822141bfd05a853236b504869ebc6b70159afc570e1d5a20641782eaa/pyyaml_env_tag-1.1.tar.gz", hash = "sha256:2eb38b75a2d21ee0475d6d97ec19c63287a7e140231e4214969d0eac923cd7ff", size = 5737, upload-time = "2025-05-13T15:24:01.64Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/04/11/432f32f8097b03e3cd5fe57e88efb685d964e2e5178a48ed61e841f7fdce/pyyaml_env_tag-1.1-py3-none-any.whl", hash = "sha256:17109e1a528561e32f026364712fee1264bc2ea6715120891174ed1b980d2e04", size = 4722, upload-time = "2025-05-13T15:23:59.629Z" }, +] + [[package]] name = "readme-renderer" version = "44.0" @@ -3725,6 +3992,30 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/3d/d8/2083a1daa7439a66f3a48589a57d576aa117726762618f6bb09fe3798796/uvicorn-0.40.0-py3-none-any.whl", hash = "sha256:c6c8f55bc8bf13eb6fa9ff87ad62308bbbc33d0b67f84293151efe87e0d5f2ee", size = 68502, upload-time = "2025-12-21T14:16:21.041Z" }, ] +[[package]] +name = "watchdog" +version = "6.0.0" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/db/7d/7f3d619e951c88ed75c6037b246ddcf2d322812ee8ea189be89511721d54/watchdog-6.0.0.tar.gz", hash = "sha256:9ddf7c82fda3ae8e24decda1338ede66e1c99883db93711d8fb941eaa2d8c282", size = 131220, upload-time = "2024-11-01T14:07:13.037Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/39/ea/3930d07dafc9e286ed356a679aa02d777c06e9bfd1164fa7c19c288a5483/watchdog-6.0.0-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:bdd4e6f14b8b18c334febb9c4425a878a2ac20efd1e0b231978e7b150f92a948", size = 96471, upload-time = "2024-11-01T14:06:37.745Z" }, + { url = "https://files.pythonhosted.org/packages/12/87/48361531f70b1f87928b045df868a9fd4e253d9ae087fa4cf3f7113be363/watchdog-6.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:c7c15dda13c4eb00d6fb6fc508b3c0ed88b9d5d374056b239c4ad1611125c860", size = 88449, upload-time = "2024-11-01T14:06:39.748Z" }, + { url = "https://files.pythonhosted.org/packages/5b/7e/8f322f5e600812e6f9a31b75d242631068ca8f4ef0582dd3ae6e72daecc8/watchdog-6.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6f10cb2d5902447c7d0da897e2c6768bca89174d0c6e1e30abec5421af97a5b0", size = 89054, upload-time = "2024-11-01T14:06:41.009Z" }, + { url = "https://files.pythonhosted.org/packages/68/98/b0345cabdce2041a01293ba483333582891a3bd5769b08eceb0d406056ef/watchdog-6.0.0-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:490ab2ef84f11129844c23fb14ecf30ef3d8a6abafd3754a6f75ca1e6654136c", size = 96480, upload-time = "2024-11-01T14:06:42.952Z" }, + { url = "https://files.pythonhosted.org/packages/85/83/cdf13902c626b28eedef7ec4f10745c52aad8a8fe7eb04ed7b1f111ca20e/watchdog-6.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:76aae96b00ae814b181bb25b1b98076d5fc84e8a53cd8885a318b42b6d3a5134", size = 88451, upload-time = "2024-11-01T14:06:45.084Z" }, + { url = "https://files.pythonhosted.org/packages/fe/c4/225c87bae08c8b9ec99030cd48ae9c4eca050a59bf5c2255853e18c87b50/watchdog-6.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a175f755fc2279e0b7312c0035d52e27211a5bc39719dd529625b1930917345b", size = 89057, upload-time = "2024-11-01T14:06:47.324Z" }, + { url = "https://files.pythonhosted.org/packages/a9/c7/ca4bf3e518cb57a686b2feb4f55a1892fd9a3dd13f470fca14e00f80ea36/watchdog-6.0.0-py3-none-manylinux2014_aarch64.whl", hash = "sha256:7607498efa04a3542ae3e05e64da8202e58159aa1fa4acddf7678d34a35d4f13", size = 79079, upload-time = "2024-11-01T14:06:59.472Z" }, + { url = "https://files.pythonhosted.org/packages/5c/51/d46dc9332f9a647593c947b4b88e2381c8dfc0942d15b8edc0310fa4abb1/watchdog-6.0.0-py3-none-manylinux2014_armv7l.whl", hash = "sha256:9041567ee8953024c83343288ccc458fd0a2d811d6a0fd68c4c22609e3490379", size = 79078, upload-time = "2024-11-01T14:07:01.431Z" }, + { url = "https://files.pythonhosted.org/packages/d4/57/04edbf5e169cd318d5f07b4766fee38e825d64b6913ca157ca32d1a42267/watchdog-6.0.0-py3-none-manylinux2014_i686.whl", hash = "sha256:82dc3e3143c7e38ec49d61af98d6558288c415eac98486a5c581726e0737c00e", size = 79076, upload-time = "2024-11-01T14:07:02.568Z" }, + { url = "https://files.pythonhosted.org/packages/ab/cc/da8422b300e13cb187d2203f20b9253e91058aaf7db65b74142013478e66/watchdog-6.0.0-py3-none-manylinux2014_ppc64.whl", hash = "sha256:212ac9b8bf1161dc91bd09c048048a95ca3a4c4f5e5d4a7d1b1a7d5752a7f96f", size = 79077, upload-time = "2024-11-01T14:07:03.893Z" }, + { url = "https://files.pythonhosted.org/packages/2c/3b/b8964e04ae1a025c44ba8e4291f86e97fac443bca31de8bd98d3263d2fcf/watchdog-6.0.0-py3-none-manylinux2014_ppc64le.whl", hash = "sha256:e3df4cbb9a450c6d49318f6d14f4bbc80d763fa587ba46ec86f99f9e6876bb26", size = 79078, upload-time = "2024-11-01T14:07:05.189Z" }, + { url = "https://files.pythonhosted.org/packages/62/ae/a696eb424bedff7407801c257d4b1afda455fe40821a2be430e173660e81/watchdog-6.0.0-py3-none-manylinux2014_s390x.whl", hash = "sha256:2cce7cfc2008eb51feb6aab51251fd79b85d9894e98ba847408f662b3395ca3c", size = 79077, upload-time = "2024-11-01T14:07:06.376Z" }, + { url = "https://files.pythonhosted.org/packages/b5/e8/dbf020b4d98251a9860752a094d09a65e1b436ad181faf929983f697048f/watchdog-6.0.0-py3-none-manylinux2014_x86_64.whl", hash = "sha256:20ffe5b202af80ab4266dcd3e91aae72bf2da48c0d33bdb15c66658e685e94e2", size = 79078, upload-time = "2024-11-01T14:07:07.547Z" }, + { url = "https://files.pythonhosted.org/packages/07/f6/d0e5b343768e8bcb4cda79f0f2f55051bf26177ecd5651f84c07567461cf/watchdog-6.0.0-py3-none-win32.whl", hash = "sha256:07df1fdd701c5d4c8e55ef6cf55b8f0120fe1aef7ef39a1c6fc6bc2e606d517a", size = 79065, upload-time = "2024-11-01T14:07:09.525Z" }, + { url = "https://files.pythonhosted.org/packages/db/d9/c495884c6e548fce18a8f40568ff120bc3a4b7b99813081c8ac0c936fa64/watchdog-6.0.0-py3-none-win_amd64.whl", hash = "sha256:cbafb470cf848d93b5d013e2ecb245d4aa1c8fd0504e863ccefa32445359d680", size = 79070, upload-time = "2024-11-01T14:07:10.686Z" }, + { url = "https://files.pythonhosted.org/packages/33/e8/e40370e6d74ddba47f002a32919d91310d6074130fe4e17dabcafc15cbf1/watchdog-6.0.0-py3-none-win_ia64.whl", hash = "sha256:a1914259fa9e1454315171103c6a30961236f508b9b623eae470268bbcc6a22f", size = 79067, upload-time = "2024-11-01T14:07:11.845Z" }, +] + [[package]] name = "wcwidth" version = "0.2.14" From c2e674df09e5da47faeea038c25b1a4d8d5fe36d Mon Sep 17 00:00:00 2001 From: Major Hayden Date: Thu, 22 Jan 2026 17:03:46 -0600 Subject: [PATCH 2/5] feat(docs): migrate documentation from Jekyll to MkDocs - Remove Jekyll frontmatter from docs/index.md - Convert absolute URLs to relative markdown links - Add full navigation structure to mkdocs.yml - Delete Jekyll configuration files (_config.yml, Gemfile, README.md) Signed-off-by: Major Hayden --- docs/Gemfile | 33 --------------------- docs/README.md | 67 ------------------------------------------ docs/_config.yml | 26 ----------------- docs/index.md | 76 +++++++++++++++--------------------------------- mkdocs.yml | 23 ++++++++++++++- 5 files changed, 45 insertions(+), 180 deletions(-) delete mode 100644 docs/Gemfile delete mode 100644 docs/README.md delete mode 100644 docs/_config.yml diff --git a/docs/Gemfile b/docs/Gemfile deleted file mode 100644 index eaff86bab..000000000 --- a/docs/Gemfile +++ /dev/null @@ -1,33 +0,0 @@ -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -source "https://rubygems.org" - -# Hello! This is where you manage which Jekyll version is used to run. -# When you want to use a different version, change it below, save the -# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: -# -# bundle exec jekyll serve -# -# This will help ensure the proper Jekyll version is running. -# Happy Jekylling! -# gem "jekyll", "~> 3.8.5" - -# If you want to use GitHub Pages, remove the "gem "jekyll"" above and -# uncomment the line below. To upgrade, run `bundle update github-pages`. -gem "github-pages", "~> 232", group: :jekyll_plugins - -# If you have any plugins, put them here! -group :jekyll_plugins do - gem "jekyll-feed", "~> 0.6" - gem "jekyll-remote-theme", "~> 0.4.1" -end diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 8b3957c8c..000000000 --- a/docs/README.md +++ /dev/null @@ -1,67 +0,0 @@ -# Lightspeed-Stack Documentation - -Welcome. This directory is published via GitHub Pages. -See the full documentation at [`../README.md`](../README.md) or browse sub-pages in `docs/`. - - - -![Logo](https://lightspeed-core.github.io/lightspeed-stack/logo.jpg) - -## Overview - -[Architecture](https://lightspeed-core.github.io/lightspeed-stack/ARCHITECTURE.html) - -[Architecture diagram](https://lightspeed-core.github.io/lightspeed-stack/architecture.svg) - -[Getting started](https://lightspeed-core.github.io/lightspeed-stack/getting_started.html) - -[Authentication and Authorization](https://lightspeed-core.github.io/lightspeed-stack/auth.html) - - - -## Installation and configuration - -[Deployment Guide](https://lightspeed-core.github.io/lightspeed-stack/deployment_guide.html) - -[Linux](https://lightspeed-core.github.io/lightspeed-stack/installation_linux.html) - -[MacOS](https://lightspeed-core.github.io/lightspeed-stack/installation_macos.html) - -[Configuration](https://lightspeed-core.github.io/lightspeed-stack/config.html) - - - -## API - -[OpenAPI specification](https://lightspeed-core.github.io/lightspeed-stack/openapi.html) - -[Conversations API](https://lightspeed-core.github.io/lightspeed-stack/conversations_api.html) - -[A2A [Agent-to-Agent] Protocol](https://lightspeed-core.github.io/lightspeed-stack/a2a_protocol.html) - - - - -## RAG and BYOK - -[RAG Configuration Guide](https://lightspeed-core.github.io/lightspeed-stack/rag_guide.html) - -[BYOK guide](https://lightspeed-core.github.io/lightspeed-stack/byok_guide.html) - - -## Other features - -[Providers](https://lightspeed-core.github.io/lightspeed-stack/providers.html) - -[User data collection](https://lightspeed-core.github.io/lightspeed-stack/user_data_collection.html) - -[Database structure](https://lightspeed-core.github.io/lightspeed-stack/DB/index.html) - - - -## Testing - -[Testing](https://lightspeed-core.github.io/lightspeed-stack/testing.html) - -[List of e2e scenarios](https://lightspeed-core.github.io/lightspeed-stack/e2e_scenarios.html) - diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index a93058951..000000000 --- a/docs/_config.yml +++ /dev/null @@ -1,26 +0,0 @@ -title: Lightspeed core service -description: Lightspeed core service -baseurl: "/lightspeed-stack" -url: "https://lightspeed-core.github.io/lightspeed-stack/" - -heading_anchors: true -search_enabled: true - -aux_links: - "Github repository": - - "https://github.com/lightspeed-core/lightspeed-stack/" - -footer_content: "Copyright © 2025 Red Hat and external authors" - -# Build settings -markdown: kramdown - -exclude: - - Gemfile - - Gemfile.lock - - vendor/ - - sources.tmpl.md - -remote_theme: pages-themes/slate@v0.2.0 -plugins: -- jekyll-remote-theme diff --git a/docs/index.md b/docs/index.md index 4136e8c5e..f9fb4351c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,71 +1,41 @@ ---- -layout: default -nav_order: 1 ---- +# Lightspeed Core Stack -# Lightspeed core stack +Lightspeed Core Stack (LCS) is an AI-powered assistant that provides answers to product questions using backend LLM services, agents, and RAG databases. -About The Project - -Lightspeed Core Stack (LCS) is an AI powered assistant that provides answers to product questions using backend LLM services, agents, and RAG databases. - -![Logo](https://lightspeed-core.github.io/lightspeed-stack/logo.jpg) +![Logo](logo.jpg) ## Overview -[Architecture](https://lightspeed-core.github.io/lightspeed-stack/ARCHITECTURE.html) - -[Architecture diagram](https://lightspeed-core.github.io/lightspeed-stack/architecture.svg) - -[Getting started](https://lightspeed-core.github.io/lightspeed-stack/getting_started.html) - -[Authentication and Authorization](https://lightspeed-core.github.io/lightspeed-stack/auth.html) - - - -## Installation and configuration - -[Deployment Guide](https://lightspeed-core.github.io/lightspeed-stack/deployment_guide.html) - -[Linux](https://lightspeed-core.github.io/lightspeed-stack/installation_linux.html) - -[MacOS](https://lightspeed-core.github.io/lightspeed-stack/installation_macos.html) - -[Configuration](https://lightspeed-core.github.io/lightspeed-stack/config.html) +- [Architecture](ARCHITECTURE.md) +- [Architecture diagram](architecture.svg) +- [Getting started](getting_started.md) +- [Authentication and Authorization](auth.md) +## Installation and Configuration +- [Deployment Guide](deployment_guide.md) +- [Linux](installation_linux.md) +- [macOS](installation_macos.md) +- [Configuration](config.md) ## API -[OpenAPI specification](https://lightspeed-core.github.io/lightspeed-stack/openapi.html) - -[Conversations API](https://lightspeed-core.github.io/lightspeed-stack/conversations_api.html) - -[A2A [Agent-to-Agent] Protocol](https://lightspeed-core.github.io/lightspeed-stack/a2a_protocol.html) - - - +- [OpenAPI specification](openapi.md) +- [Conversations API](conversations_api.md) +- [A2A (Agent-to-Agent) Protocol](a2a_protocol.md) ## RAG and BYOK -[RAG Configuration Guide](https://lightspeed-core.github.io/lightspeed-stack/rag_guide.html) - -[BYOK guide](https://lightspeed-core.github.io/lightspeed-stack/byok_guide.html) - - -## Other features - -[Providers](https://lightspeed-core.github.io/lightspeed-stack/providers.html) - -[User data collection](https://lightspeed-core.github.io/lightspeed-stack/user_data_collection.html) - -[Database structure](https://lightspeed-core.github.io/lightspeed-stack/DB/index.html) +- [RAG Configuration Guide](rag_guide.md) +- [BYOK Guide](byok_guide.md) +## Other Features +- [Providers](providers.md) +- [User data collection](user_data_collection.md) +- [Database structure](DB/index.html) ## Testing -[Testing](https://lightspeed-core.github.io/lightspeed-stack/testing.html) - -[List of e2e scenarios](https://lightspeed-core.github.io/lightspeed-stack/e2e_scenarios.html) - +- [Testing](testing.md) +- [List of E2E scenarios](e2e_scenarios.md) diff --git a/mkdocs.yml b/mkdocs.yml index 594021070..a606832f2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,27 @@ markdown_extensions: - toc: permalink: true -# Minimal nav for infrastructure PR - will be expanded in PR 2 nav: - Home: index.md + - Getting Started: + - Getting Started: getting_started.md + - Installation (Linux): installation_linux.md + - Installation (macOS): installation_macos.md + - Configuration: + - Configuration Guide: config.md + - Providers: providers.md + - RAG Guide: rag_guide.md + - BYOK Guide: byok_guide.md + - Architecture: + - Overview: ARCHITECTURE.md + - Authentication: auth.md + - A2A Protocol: a2a_protocol.md + - API: + - OpenAPI: openapi.md + - Conversations API: conversations_api.md + - Deployment: + - Deployment Guide: deployment_guide.md + - User Data Collection: user_data_collection.md + - Testing: + - Testing Guide: testing.md + - E2E Scenarios: e2e_scenarios.md From ba222453de986f05364157557929a0378287efb8 Mon Sep 17 00:00:00 2001 From: Major Hayden Date: Thu, 22 Jan 2026 17:05:29 -0600 Subject: [PATCH 3/5] feat(docs): add API reference generation and GitHub Actions deployment - Add mkdocstrings plugin configuration for auto-generated API docs - Create scripts/gen_api_ref.py to generate API reference from docstrings - Add gen-files, literate-nav, and section-index plugins - Create .github/workflows/docs.yaml for GitHub Pages deployment - API Reference section added to navigation The workflow builds docs on PRs for validation and deploys to GitHub Pages on pushes to main branch. Signed-off-by: Major Hayden --- .github/workflows/docs.yaml | 70 +++++++++++++++++++++++++++++++++++++ mkdocs.yml | 21 +++++++++++ scripts/gen_api_ref.py | 37 ++++++++++++++++++++ 3 files changed, 128 insertions(+) create mode 100644 .github/workflows/docs.yaml create mode 100644 scripts/gen_api_ref.py diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 000000000..056a8b26e --- /dev/null +++ b/.github/workflows/docs.yaml @@ -0,0 +1,70 @@ +name: docs + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'src/**' + - 'mkdocs.yml' + - 'scripts/gen_api_ref.py' + - '.github/workflows/docs.yaml' + pull_request: + branches: + - main + paths: + - 'docs/**' + - 'src/**' + - 'mkdocs.yml' + - 'scripts/gen_api_ref.py' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install uv + uses: astral-sh/setup-uv@v4 + + - name: Install dependencies + run: uv sync --group docs + + - name: Build documentation + run: uv run mkdocs build + + - name: Upload artifact + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@v3 + with: + path: site/ + + deploy: + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/mkdocs.yml b/mkdocs.yml index a606832f2..4cc4d030d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,6 +33,26 @@ theme: plugins: - search + - mkdocstrings: + default_handler: python + handlers: + python: + paths: [src] + options: + show_source: true + show_root_heading: true + show_symbol_type_heading: true + show_symbol_type_toc: true + docstring_style: google + members_order: source + separate_signature: true + signature_crossrefs: true + - gen-files: + scripts: + - scripts/gen_api_ref.py + - literate-nav: + nav_file: SUMMARY.md + - section-index markdown_extensions: - pymdownx.highlight: @@ -63,6 +83,7 @@ nav: - API: - OpenAPI: openapi.md - Conversations API: conversations_api.md + - API Reference: reference/ - Deployment: - Deployment Guide: deployment_guide.md - User Data Collection: user_data_collection.md diff --git a/scripts/gen_api_ref.py b/scripts/gen_api_ref.py new file mode 100644 index 000000000..09eb7504a --- /dev/null +++ b/scripts/gen_api_ref.py @@ -0,0 +1,37 @@ +#!/usr/bin/env python3 +"""Generate API reference pages for mkdocstrings.""" + +from pathlib import Path + +import mkdocs_gen_files + +nav = mkdocs_gen_files.Nav() +src_root = Path("src") + +for path in sorted(src_root.rglob("*.py")): + if path.name.startswith("_") and path.name != "__init__.py": + continue + + module_path = path.relative_to(src_root).with_suffix("") + doc_path = path.relative_to(src_root).with_suffix(".md") + full_doc_path = Path("reference", doc_path) + + parts = tuple(module_path.parts) + if parts[-1] == "__init__": + parts = parts[:-1] + doc_path = doc_path.with_name("index.md") + full_doc_path = full_doc_path.with_name("index.md") + + if not parts: + continue + + nav[parts] = doc_path.as_posix() + + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + ident = ".".join(parts) + fd.write(f"::: {ident}\n") + + mkdocs_gen_files.set_edit_path(full_doc_path, path) + +with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file: + nav_file.writelines(nav.build_literate_nav()) From 141d9751c16db1a8d0bfe9a98e5b0b756e00779d Mon Sep 17 00:00:00 2001 From: Major Hayden Date: Thu, 22 Jan 2026 17:08:10 -0600 Subject: [PATCH 4/5] refactor(make): consolidate documentation targets - Remove duplicate 'generate-documentation' target - Rename 'doc' to 'docs-readmes' for clarity (generates README.md files) - Add 'uv run' prefix to docs-readmes for consistency - Keep 'docs-build' and 'docs-serve' for MkDocs operations Signed-off-by: Major Hayden --- Makefile | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/Makefile b/Makefile index ffdc9d1d1..35dce5161 100644 --- a/Makefile +++ b/Makefile @@ -57,22 +57,19 @@ openapi-doc: docs/openapi.json scripts/fix_openapi_doc.py ## Generate OpenAPI do python3 scripts/fix_openapi_doc.py < output.md > docs/openapi.md rm output.md -generate-documentation: ## Generate documentation - scripts/gen_doc.py - # TODO uv migration requirements.txt: pyproject.toml pdm.lock ## Generate requirements.txt file containing hashes for all non-devel packages pdm export --prod --format requirements --output requirements.txt --no-extras --without evaluation -doc: ## Generate documentation for developers - scripts/gen_doc.py - -docs-build: ## Build MkDocs documentation +docs-build: ## Build MkDocs documentation site uv run mkdocs build docs-serve: ## Serve MkDocs documentation locally with hot-reload uv run mkdocs serve +docs-readmes: ## Generate README.md files in source directories + uv run scripts/gen_doc.py + docs/config.puml: src/models/config.py ## Generate PlantUML class diagram for configuration pyreverse src/models/config.py --output puml --output-directory=docs/ mv docs/classes.puml docs/config.puml From 99fb2ba846341c2b5597a0e20839e61e5b940be2 Mon Sep 17 00:00:00 2001 From: Major Hayden Date: Fri, 23 Jan 2026 11:51:38 -0600 Subject: [PATCH 5/5] fix(ci): add workflow file to pull_request trigger paths - Include docs.yaml in pull_request paths to trigger validation builds when the workflow itself is modified Signed-off-by: Major Hayden --- .github/workflows/docs.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 056a8b26e..bd37a3802 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -18,6 +18,7 @@ on: - 'src/**' - 'mkdocs.yml' - 'scripts/gen_api_ref.py' + - '.github/workflows/docs.yaml' workflow_dispatch: permissions: