src.services.sphinx_services

Module Contents

src.services.sphinx_services.logger

src.services.sphinx_services.DOCS_SCAFFOLD_DIR

src.services.sphinx_services.DOCS_ASSET_DIR

src.services.sphinx_services.AUTOAPI_DOCSTRING_THRESHOLD = 0.5

src.services.sphinx_services.SPHINX_CONF_CANDIDATES

src.services.sphinx_services.SAMPLE_DOCS_FALLBACK_TEXTS

src.services.sphinx_services.AUTOAPI_CONF_MARKER_START = '# AUTODOC AUTOAPI RUNTIME SETTINGS START'

src.services.sphinx_services.AUTOAPI_CONF_MARKER_END = '# AUTODOC AUTOAPI RUNTIME SETTINGS END'

src.services.sphinx_services.AUTOAPI_WARNINGS_TO_SUPPRESS = ['autoapi.python_import_resolution']

src.services.sphinx_services.DEFAULT_AUTOAPI_IGNORE_PATTERNS = ['*/migrations/*', '*/migrations.py', '*/tests/*', '*/test_*.py', '*/urls.py', '*/urls_*.py',...

src.services.sphinx_services.RISKY_AUTOAPI_PATH_PATTERNS

src.services.sphinx_services.LOW_CONTENT_MIN_MEANINGFUL_LINES = 4

exception src.services.sphinx_services.PublishPagesError(message: str, status_code: int = 403)

Bases: RuntimeError

Raised when a GitHub Pages publish step fails.

status_code = 403

src.services.sphinx_services.create_sphinx_setup(provider, repo_url, token, branch, docstring_analysis_file, docstring_threshold: float = AUTOAPI_DOCSTRING_THRESHOLD, low_content_min_meaningful_lines: int = LOW_CONTENT_MIN_MEANINGFUL_LINES)

Set up Sphinx documentation for a repository based on docstring coverage.

Args:

provider (str): The version control provider (e.g., ‘gitlab’ or ‘github’). repo_url (str): The URL of the repository. token (str): Access token for the repository. branch (str): The branch to set up documentation on. docstring_analysis_file (str): Path to the CSV file containing docstring analysis.

Returns:

bool: True if setup is successful, False otherwise.

src.services.sphinx_services.publish_github_pages(repo_url: str, source_branch: str, token: str, low_content_min_meaningful_lines: int = LOW_CONTENT_MIN_MEANINGFUL_LINES) → bool

Publishes reviewed GitHub docs output from a source branch to gh-pages.

src.services.sphinx_services.trigger_gitlab_pipeline(repo_url: str, branch: str, token: str, variables: dict[str, str] | None = None) → bool

Triggers a GitLab pipeline for the given project and branch.

Parameters:

• repo_url (str) – The GitLab project path (e.g., ‘namespace/project’).

• branch (str) – The branch to trigger the pipeline on.

• token (str) – GitLab private token.

• variables (dict, optional) – Pipeline variables.

Returns:

True if the pipeline was triggered successfully, False otherwise.

Return type:

bool

src.services.sphinx_services.detect_navigation_conflict(existing_index_content: str | None, toctree_entry: str) → tuple[bool, str | None]

Detects whether an existing index.rst already references a conflicting entry.

A conflict exists when a toctree entry with the same leaf page name already points somewhere other than the proposed architecture doc location.

Parameters:

• existing_index_content (str | None) – Current contents of index.rst, if known.

• toctree_entry (str) – Proposed toctree entry for the architecture draft.

Returns:

Whether a conflict was found, and the conflicting line.

Return type:

tuple[bool, str | None]

src.services.sphinx_services.propose_architecture_navigation(repo_path: str, branch: str, token: str, provider: str, output_path: str) → dict

Proposes where a generated architecture draft should be linked in the Sphinx navigation.

Parameters:

• repo_path (str) – Repository path (e.g., ‘user/repo’).

• branch (str) – Branch to inspect for the existing index.rst.

• token (str) – Access token used for the read-only lookup.

• provider (str) – Git provider (‘github’ or ‘gitlab’).

• output_path (str) – Proposed architecture documentation output path.

Returns:

Navigation placement proposal including any detected conflict.

Return type:

dict

src.services.sphinx_services.update_sphinx_navigation_for_architecture(repo_path: str, branch: str, token: str, provider: str, navigation_update: dict) → bool

Applies a proposed navigation update for an approved architecture document.

Parameters:

• repo_path (str) – Repository path (e.g., ‘user/repo’).

• branch (str) – Branch receiving the update.

• token (str) – Access token used for the write operation.

• provider (str) – Git provider (‘github’ or ‘gitlab’).

• navigation_update (dict) – Proposal produced by propose_architecture_navigation.

Returns:

True if the navigation is already correct or was updated successfully.

Return type:

bool

src.services.sphinx_services.apply_approved_architecture_document(repo_path: str, branch: str, token: str, provider: str, output_path: str, content: str) → bool

Writes an approved architecture document to the target repository documentation path.

Parameters:

• repo_path (str) – Repository path (e.g., ‘user/repo’).

• branch (str) – Branch receiving the approved document.

• token (str) – Access token used for the write operation.

• provider (str) – Git provider (‘github’ or ‘gitlab’).

• output_path (str) – Documentation path to create or update.

• content (str) – Approved architecture document content.

Returns:

True if the write succeeded, False otherwise.

Return type:

bool