docs: add Sphinx documentation build and deploy workflow
Some checks failed
CVE Scan & Docker Build / security-scan (push) Successful in 3m12s
CVE Scan & Docker Build / build-and-push (push) Successful in 2m38s
Build & Deploy Docs / build-and-deploy (push) Failing after 1m31s

- Add Gitea Actions workflow to build and deploy docs on push to main
- Generate Sphinx reference documentation for all apps and modules
- Deploy versioned and latest docs via rsync over SSH
This commit is contained in:
2026-05-23 06:11:05 -04:00
parent 50dffe688b
commit f8a2cf0c3d
114 changed files with 1797 additions and 2 deletions

View File

97
docs/source/conf.py Normal file
View File

@@ -0,0 +1,97 @@
import os
import sys
import tomllib
# The Django package lives at <repo>/mnemosyne/<inner mnemosyne>/. Adding the
# outer mnemosyne/ directory to sys.path lets autodoc resolve every app
# (themis, library, llm_manager, mcp_server) and the project settings module.
sys.path.insert(0, os.path.abspath('../../mnemosyne'))
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'mnemosyne.settings')
# Load real .env if present (local dev). In CI there is none and that's fine —
# settings.py provides a default for every env var it reads, so the import
# succeeds either way.
_repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
_env_file = os.path.join(_repo_root, 'mnemosyne', '.env')
if os.path.exists(_env_file):
with open(_env_file) as _f:
for _line in _f:
_line = _line.strip()
if not _line or _line.startswith('#') or '=' not in _line:
continue
_key, _val = _line.split('=', 1)
os.environ.setdefault(_key.strip(), _val.strip())
import django # noqa: E402
django.setup()
# Sphinx autodoc calls repr() on every class attribute it documents. Django's
# QuerySet.__repr__ executes a SELECT against the database — which doc builds
# have no business doing. Intercept object_description so QuerySet instances
# render as a static string instead. Mnemosyne's themis app has at least one
# DRF viewset with a class-level queryset attribute, so this matters.
from django.db.models.query import QuerySet # noqa: E402
import sphinx.util.inspect as _sphinx_inspect # noqa: E402
_orig_object_description = _sphinx_inspect.object_description
def _safe_object_description(obj, *args, **kwargs):
if isinstance(obj, QuerySet):
return f'<QuerySet [{obj.model.__name__}]>'
return _orig_object_description(obj, *args, **kwargs)
_sphinx_inspect.object_description = _safe_object_description
# ── Sphinx configuration ──────────────────────────────────────────────────
project = 'Mnemosyne'
copyright = '2026, Mnemosyne Team'
author = 'Mnemosyne Team'
with open(os.path.join(_repo_root, 'pyproject.toml'), 'rb') as _f:
release = tomllib.load(_f)['project']['version']
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.napoleon',
'sphinx.ext.intersphinx',
'sphinx_autodoc_typehints',
'sphinxcontrib.httpdomain',
'sphinxcontrib.mermaid',
'myst_parser',
]
source_suffix = {'.rst': 'restructuredtext', '.md': 'markdown'}
myst_enable_extensions = ['colon_fence', 'deflist', 'tasklist', 'attrs_inline']
myst_heading_anchors = 4
autodoc_default_options = {
'members': True,
'member-order': 'bysource',
'special-members': '__init__',
'undoc-members': True,
'exclude-members': '__weakref__',
}
autodoc_inherit_docstrings = False
napoleon_use_ivar = True
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'django': ('https://docs.djangoproject.com/en/stable/',
'https://docs.djangoproject.com/en/stable/_objects/'),
}
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_theme_options = {
'navigation_depth': 4,
'collapse_navigation': False,
'sticky_navigation': True,
'includehidden': True,
'titles_only': False,
}

17
docs/source/index.rst Normal file
View File

@@ -0,0 +1,17 @@
Mnemosyne Documentation
=======================
Content-type-aware, multimodal personal knowledge management system.
.. toctree::
:maxdepth: 2
:caption: API Reference
reference/apps/index
Indices
-------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

@@ -0,0 +1,10 @@
Applications
============
.. toctree::
:maxdepth: 2
themis/modules
library/modules
llm_manager/modules
mcp_server/modules

View File

@@ -0,0 +1,7 @@
library.admin module
====================
.. automodule:: library.admin
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,18 @@
library.api package
===================
.. automodule:: library.api
:members:
:show-inheritance:
:undoc-members:
Submodules
----------
.. toctree::
:maxdepth: 4
library.api.serializers
library.api.urls
library.api.views
library.api.workspaces

View File

@@ -0,0 +1,7 @@
library.api.serializers module
==============================
.. automodule:: library.api.serializers
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.api.urls module
=======================
.. automodule:: library.api.urls
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.api.views module
========================
.. automodule:: library.api.views
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.api.workspaces module
=============================
.. automodule:: library.api.workspaces
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.apps module
===================
.. automodule:: library.apps
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.content\_types module
=============================
.. automodule:: library.content_types
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.forms module
====================
.. automodule:: library.forms
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.management.commands.embed\_collection module
====================================================
.. automodule:: library.management.commands.embed_collection
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.management.commands.embed\_item module
==============================================
.. automodule:: library.management.commands.embed_item
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.management.commands.embedding\_status module
====================================================
.. automodule:: library.management.commands.embedding_status
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.management.commands.load\_library\_types module
=======================================================
.. automodule:: library.management.commands.load_library_types
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,21 @@
library.management.commands package
===================================
.. automodule:: library.management.commands
:members:
:show-inheritance:
:undoc-members:
Submodules
----------
.. toctree::
:maxdepth: 4
library.management.commands.embed_collection
library.management.commands.embed_item
library.management.commands.embedding_status
library.management.commands.load_library_types
library.management.commands.search
library.management.commands.search_stats
library.management.commands.setup_neo4j_indexes

View File

@@ -0,0 +1,7 @@
library.management.commands.search module
=========================================
.. automodule:: library.management.commands.search
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.management.commands.search\_stats module
================================================
.. automodule:: library.management.commands.search_stats
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.management.commands.setup\_neo4j\_indexes module
========================================================
.. automodule:: library.management.commands.setup_neo4j_indexes
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,15 @@
library.management package
==========================
.. automodule:: library.management
:members:
:show-inheritance:
:undoc-members:
Subpackages
-----------
.. toctree::
:maxdepth: 4
library.management.commands

View File

@@ -0,0 +1,7 @@
library.metrics module
======================
.. automodule:: library.metrics
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.models module
=====================
.. automodule:: library.models
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,34 @@
library package
===============
.. automodule:: library
:members:
:show-inheritance:
:undoc-members:
Subpackages
-----------
.. toctree::
:maxdepth: 4
library.api
library.management
library.services
Submodules
----------
.. toctree::
:maxdepth: 4
library.admin
library.apps
library.content_types
library.forms
library.metrics
library.models
library.tasks
library.urls
library.utils
library.views

View File

@@ -0,0 +1,7 @@
library.services.chunker module
===============================
.. automodule:: library.services.chunker
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.services.concepts module
================================
.. automodule:: library.services.concepts
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.services.daedalus\_s3 module
====================================
.. automodule:: library.services.daedalus_s3
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.services.embedding\_client module
=========================================
.. automodule:: library.services.embedding_client
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.services.fusion module
==============================
.. automodule:: library.services.fusion
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.services.parsers module
===============================
.. automodule:: library.services.parsers
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.services.pipeline module
================================
.. automodule:: library.services.pipeline
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.services.reranker module
================================
.. automodule:: library.services.reranker
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,25 @@
library.services package
========================
.. automodule:: library.services
:members:
:show-inheritance:
:undoc-members:
Submodules
----------
.. toctree::
:maxdepth: 4
library.services.chunker
library.services.concepts
library.services.daedalus_s3
library.services.embedding_client
library.services.fusion
library.services.parsers
library.services.pipeline
library.services.reranker
library.services.search
library.services.text_utils
library.services.vision

View File

@@ -0,0 +1,7 @@
library.services.search module
==============================
.. automodule:: library.services.search
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.services.text\_utils module
===================================
.. automodule:: library.services.text_utils
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.services.vision module
==============================
.. automodule:: library.services.vision
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.tasks module
====================
.. automodule:: library.tasks
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.urls module
===================
.. automodule:: library.urls
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.utils module
====================
.. automodule:: library.utils
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library.views module
====================
.. automodule:: library.views
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
library
=======
.. toctree::
:maxdepth: 4
library

View File

@@ -0,0 +1,7 @@
llm\_manager.admin module
=========================
.. automodule:: llm_manager.admin
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,17 @@
llm\_manager.api package
========================
.. automodule:: llm_manager.api
:members:
:show-inheritance:
:undoc-members:
Submodules
----------
.. toctree::
:maxdepth: 4
llm_manager.api.serializers
llm_manager.api.urls
llm_manager.api.views

View File

@@ -0,0 +1,7 @@
llm\_manager.api.serializers module
===================================
.. automodule:: llm_manager.api.serializers
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
llm\_manager.api.urls module
============================
.. automodule:: llm_manager.api.urls
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
llm\_manager.api.views module
=============================
.. automodule:: llm_manager.api.views
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
llm\_manager.apps module
========================
.. automodule:: llm_manager.apps
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
llm\_manager.encryption module
==============================
.. automodule:: llm_manager.encryption
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
llm\_manager.forms module
=========================
.. automodule:: llm_manager.forms
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
llm\_manager.management.commands.load\_default\_llm\_models module
==================================================================
.. automodule:: llm_manager.management.commands.load_default_llm_models
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,15 @@
llm\_manager.management.commands package
========================================
.. automodule:: llm_manager.management.commands
:members:
:show-inheritance:
:undoc-members:
Submodules
----------
.. toctree::
:maxdepth: 4
llm_manager.management.commands.load_default_llm_models

View File

@@ -0,0 +1,15 @@
llm\_manager.management package
===============================
.. automodule:: llm_manager.management
:members:
:show-inheritance:
:undoc-members:
Subpackages
-----------
.. toctree::
:maxdepth: 4
llm_manager.management.commands

View File

@@ -0,0 +1,7 @@
llm\_manager.models module
==========================
.. automodule:: llm_manager.models
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,32 @@
llm\_manager package
====================
.. automodule:: llm_manager
:members:
:show-inheritance:
:undoc-members:
Subpackages
-----------
.. toctree::
:maxdepth: 4
llm_manager.api
llm_manager.management
Submodules
----------
.. toctree::
:maxdepth: 4
llm_manager.admin
llm_manager.apps
llm_manager.encryption
llm_manager.forms
llm_manager.models
llm_manager.services
llm_manager.tasks
llm_manager.urls
llm_manager.views

View File

@@ -0,0 +1,7 @@
llm\_manager.services module
============================
.. automodule:: llm_manager.services
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
llm\_manager.tasks module
=========================
.. automodule:: llm_manager.tasks
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
llm\_manager.urls module
========================
.. automodule:: llm_manager.urls
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
llm\_manager.views module
=========================
.. automodule:: llm_manager.views
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
llm_manager
===========
.. toctree::
:maxdepth: 4
llm_manager

View File

@@ -0,0 +1,7 @@
mcp\_server.admin module
========================
.. automodule:: mcp_server.admin
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,17 @@
mcp\_server.api package
=======================
.. automodule:: mcp_server.api
:members:
:show-inheritance:
:undoc-members:
Submodules
----------
.. toctree::
:maxdepth: 4
mcp_server.api.serializers
mcp_server.api.teams
mcp_server.api.urls

View File

@@ -0,0 +1,7 @@
mcp\_server.api.serializers module
==================================
.. automodule:: mcp_server.api.serializers
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.api.teams module
============================
.. automodule:: mcp_server.api.teams
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.api.urls module
===========================
.. automodule:: mcp_server.api.urls
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.apps module
=======================
.. automodule:: mcp_server.apps
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.auth module
=======================
.. automodule:: mcp_server.auth
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.context module
==========================
.. automodule:: mcp_server.context
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.forms module
========================
.. automodule:: mcp_server.forms
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.management.commands.backfill\_library\_memberships module
=====================================================================
.. automodule:: mcp_server.management.commands.backfill_library_memberships
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.management.commands.create\_mcp\_token module
=========================================================
.. automodule:: mcp_server.management.commands.create_mcp_token
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,17 @@
mcp\_server.management.commands package
=======================================
.. automodule:: mcp_server.management.commands
:members:
:show-inheritance:
:undoc-members:
Submodules
----------
.. toctree::
:maxdepth: 4
mcp_server.management.commands.backfill_library_memberships
mcp_server.management.commands.create_mcp_token
mcp_server.management.commands.seed_signing_key

View File

@@ -0,0 +1,7 @@
mcp\_server.management.commands.seed\_signing\_key module
=========================================================
.. automodule:: mcp_server.management.commands.seed_signing_key
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,15 @@
mcp\_server.management package
==============================
.. automodule:: mcp_server.management
:members:
:show-inheritance:
:undoc-members:
Subpackages
-----------
.. toctree::
:maxdepth: 4
mcp_server.management.commands

View File

@@ -0,0 +1,7 @@
mcp\_server.metrics module
==========================
.. automodule:: mcp_server.metrics
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.models module
=========================
.. automodule:: mcp_server.models
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,35 @@
mcp\_server package
===================
.. automodule:: mcp_server
:members:
:show-inheritance:
:undoc-members:
Subpackages
-----------
.. toctree::
:maxdepth: 4
mcp_server.api
mcp_server.management
mcp_server.tools
Submodules
----------
.. toctree::
:maxdepth: 4
mcp_server.admin
mcp_server.apps
mcp_server.auth
mcp_server.context
mcp_server.forms
mcp_server.metrics
mcp_server.models
mcp_server.server
mcp_server.teams
mcp_server.urls
mcp_server.views

View File

@@ -0,0 +1,7 @@
mcp\_server.server module
=========================
.. automodule:: mcp_server.server
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.teams module
========================
.. automodule:: mcp_server.teams
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.tools.discovery module
==================================
.. automodule:: mcp_server.tools.discovery
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.tools.health module
===============================
.. automodule:: mcp_server.tools.health
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,17 @@
mcp\_server.tools package
=========================
.. automodule:: mcp_server.tools
:members:
:show-inheritance:
:undoc-members:
Submodules
----------
.. toctree::
:maxdepth: 4
mcp_server.tools.discovery
mcp_server.tools.health
mcp_server.tools.search

View File

@@ -0,0 +1,7 @@
mcp\_server.tools.search module
===============================
.. automodule:: mcp_server.tools.search
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.urls module
=======================
.. automodule:: mcp_server.urls
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp\_server.views module
========================
.. automodule:: mcp_server.views
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
mcp_server
==========
.. toctree::
:maxdepth: 4
mcp_server

View File

@@ -0,0 +1,7 @@
themis
======
.. toctree::
:maxdepth: 4
themis

View File

@@ -0,0 +1,7 @@
themis.adapters module
======================
.. automodule:: themis.adapters
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
themis.admin module
===================
.. automodule:: themis.admin
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,17 @@
themis.api package
==================
.. automodule:: themis.api
:members:
:show-inheritance:
:undoc-members:
Submodules
----------
.. toctree::
:maxdepth: 4
themis.api.serializers
themis.api.urls
themis.api.views

View File

@@ -0,0 +1,7 @@
themis.api.serializers module
=============================
.. automodule:: themis.api.serializers
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
themis.api.urls module
======================
.. automodule:: themis.api.urls
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
themis.api.views module
=======================
.. automodule:: themis.api.views
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
themis.apps module
==================
.. automodule:: themis.apps
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
themis.context\_processors module
=================================
.. automodule:: themis.context_processors
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
themis.encryption module
========================
.. automodule:: themis.encryption
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
themis.forms module
===================
.. automodule:: themis.forms
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
themis.middleware module
========================
.. automodule:: themis.middleware
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
themis.models module
====================
.. automodule:: themis.models
:members:
:show-inheritance:
:undoc-members:

View File

@@ -0,0 +1,7 @@
themis.notifications module
===========================
.. automodule:: themis.notifications
:members:
:show-inheritance:
:undoc-members:

Some files were not shown because too many files have changed in this diff Show More