add src-docs

CONTRIBUTING.md

@@ -0,0 +1,8 @@
+## Generating src docs for every commit
+
+Run the following command:
+
+```bash
+echo -e "tox -e src-docs\ngit add src-docs\n" > .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```

generate-src-docs.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+# Copyright 2023 Canonical Ltd.
+# See LICENSE file for licensing details.
+
+rm -rf src-docs
+# There is a problem with lazydocs and using the flask Blueprint class which is causing an error,
+# skip that file
+PYTHON_FILES=$(find repo_policy_compliance -name "*.py" -not -path "**/blueprint.py")
+# The word splitting is intentional here
+# shellcheck disable=SC2086
+lazydocs --no-watermark --output-path src-docs $PYTHON_FILES

repo_policy_compliance/__init__.py

@@ -9,7 +9,7 @@
 
 from pydantic import BaseModel, Field
 
-from . import check, log, policy
+from repo_policy_compliance import check, log, policy
 
 
 class UsedPolicy(Enum):

repo_policy_compliance/blueprint.py

@@ -24,7 +24,7 @@
 from flask_pydantic import validate
 from github import GithubException
 
-from . import (
+from repo_policy_compliance import (
     PullRequestInput,
     PushInput,
     ScheduleInput,
@@ -38,7 +38,7 @@
     schedule,
     workflow_dispatch,
 )
-from .check import Result
+from repo_policy_compliance.check import Result
 
 repo_policy_compliance = Blueprint("repo_policy_compliance", __name__)
 auth = HTTPTokenAuth(scheme="Bearer")

repo_policy_compliance/check.py

@@ -10,10 +10,10 @@
 from github.Branch import Branch
 from github.Repository import Repository
 
-from . import log
-from .comment import remove_quote_lines
-from .github_client import get_branch, get_collaborators
-from .github_client import inject as inject_github_client
+from repo_policy_compliance import log
+from repo_policy_compliance.comment import remove_quote_lines
+from repo_policy_compliance.github_client import get_branch, get_collaborators
+from repo_policy_compliance.github_client import inject as inject_github_client
 
 BYPASS_ALLOWANCES_KEY = "bypass_pull_request_allowances"
 FAILURE_MESSAGE = (

repo_policy_compliance/github_client.py

@@ -13,7 +13,7 @@
 from github.Branch import Branch
 from github.Repository import Repository
 
-from .exceptions import ConfigurationError, GithubClientError
+from repo_policy_compliance.exceptions import ConfigurationError, GithubClientError
 
 P = ParamSpec("P")
 R = TypeVar("R")

src-docs/__init__.py.md

@@ -0,0 +1,75 @@
+<!-- markdownlint-disable -->
+
+<a href="../repo_policy_compliance/__init__.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+# <kbd>module</kbd> `__init__.py`
+Library for checking that GitHub repos comply with policy. 
+
+
+
+---
+
+## <kbd>class</kbd> `BranchInput`
+Input arguments to check jobs running on a branch. 
+
+Attrs:  repository_name: The name of the repository to run the check on.  branch_name: The name of the branch that the job is running on.  commit_sha: The SHA of the commit that the job is running on. 
+
+
+
+
+
+---
+
+## <kbd>class</kbd> `PullRequestInput`
+Input arguments for pull request checks. 
+
+Attrs:  repository_name: The name of the repository to run the check on.  source_repository_name: The name of the repository that has the source branch.  target_branch_name: The name of the branch that is targeted by the PR.  source_branch_name: The name of the branch that contains the commits to be merged.  commit_sha: The SHA of the commit that the job is running on. 
+
+
+
+
+
+---
+
+## <kbd>class</kbd> `BranchInput`
+Input arguments to check jobs running on a branch. 
+
+Attrs:  repository_name: The name of the repository to run the check on.  branch_name: The name of the branch that the job is running on.  commit_sha: The SHA of the commit that the job is running on. 
+
+
+
+
+
+---
+
+## <kbd>class</kbd> `BranchInput`
+Input arguments to check jobs running on a branch. 
+
+Attrs:  repository_name: The name of the repository to run the check on.  branch_name: The name of the branch that the job is running on.  commit_sha: The SHA of the commit that the job is running on. 
+
+
+
+
+
+---
+
+## <kbd>class</kbd> `UsedPolicy`
+Sentinel to indicate which policy to use. 
+
+Attrs:  ALL: Use all policies. 
+
+
+
+
+
+---
+
+## <kbd>class</kbd> `BranchInput`
+Input arguments to check jobs running on a branch. 
+
+Attrs:  repository_name: The name of the repository to run the check on.  branch_name: The name of the branch that the job is running on.  commit_sha: The SHA of the commit that the job is running on. 
+
+
+
+
+

src-docs/check.py.md

@@ -0,0 +1,37 @@
+<!-- markdownlint-disable -->
+
+<a href="../repo_policy_compliance/check.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+# <kbd>module</kbd> `check.py`
+Individual checks used to compose job checks. 
+
+**Global Variables**
+---------------
+- **BYPASS_ALLOWANCES_KEY**
+- **FAILURE_MESSAGE**
+- **AUTHORIZATION_STRING_PREFIX**
+- **EXECUTE_JOB_MESSAGE**
+
+
+---
+
+## <kbd>class</kbd> `Report`
+Reports the result of a check. 
+
+Attrs:  result: The check result.  reason: If the check failed, the reason why it failed. 
+
+
+
+
+
+---
+
+## <kbd>class</kbd> `Result`
+The result of a check. 
+
+Attrs:  PASS: The check passed.  FAIL: The check failed. 
+
+
+
+
+

src-docs/comment.py.md

@@ -0,0 +1,32 @@
+<!-- markdownlint-disable -->
+
+<a href="../repo_policy_compliance/comment.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+# <kbd>module</kbd> `comment.py`
+Module for modifying comments. 
+
+
+---
+
+<a href="../repo_policy_compliance/comment.py#L7"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `remove_quote_lines`
+
+```python
+remove_quote_lines(body: str) → str
+```
+
+Remove any lines from a comment that start with >. 
+
+
+
+**Args:**
+
+ - <b>`body`</b>:  The content of the comment. 
+
+
+
+**Returns:**
+ The comment with any lines that start with > removed. 
+
+

src-docs/exceptions.py.md

@@ -0,0 +1,45 @@
+<!-- markdownlint-disable -->
+
+<a href="../repo_policy_compliance/exceptions.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+# <kbd>module</kbd> `exceptions.py`
+All the exceptions that can be raised. 
+
+
+
+---
+
+## <kbd>class</kbd> `BaseError`
+Base class for all exceptions. 
+
+
+
+
+
+---
+
+## <kbd>class</kbd> `ConfigurationError`
+There is a problem with configuration. 
+
+
+
+
+
+---
+
+## <kbd>class</kbd> `GithubClientError`
+Error occurred on Github API. 
+
+
+
+
+
+---
+
+## <kbd>class</kbd> `InputError`
+Input is missing or unexpected. 
+
+
+
+
+

src-docs/github_client.py.md

@@ -0,0 +1,119 @@
+<!-- markdownlint-disable -->
+
+<a href="../repo_policy_compliance/github_client.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+# <kbd>module</kbd> `github_client.py`
+Module for GitHub client. 
+
+**Global Variables**
+---------------
+- **GITHUB_TOKEN_ENV_NAME**
+
+---
+
+<a href="../repo_policy_compliance/github_client.py#L25"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `get`
+
+```python
+get() → Github
+```
+
+Get a GitHub client. 
+
+
+
+**Returns:**
+  A GitHub client that is configured with a token from the environment. 
+
+
+
+**Raises:**
+
+ - <b>`ConfigurationError`</b>:  If the GitHub token environment variable is not provided or empty. 
+
+
+---
+
+<a href="../repo_policy_compliance/github_client.py#L43"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `inject`
+
+```python
+inject(func: Callable[Concatenate[Github, ~P], ~R]) → Callable[~P, ~R]
+```
+
+Injects a GitHub client as the first argument to a function. 
+
+
+
+**Args:**
+
+ - <b>`func`</b>:  The function that requires a GitHub client. 
+
+
+
+**Returns:**
+ The function where the GitHub client has been injected as the first argument. 
+
+
+---
+
+<a href="../repo_policy_compliance/github_client.py#L89"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `get_collaborators`
+
+```python
+get_collaborators(
+    affiliation: Literal['outside', 'all'],
+    permission: Literal['triage', 'maintain', 'admin', 'pull'],
+    repository: Repository
+) → list[dict]
+```
+
+Get collaborators with a given affiliation and permission. 
+
+
+
+**Args:**
+
+ - <b>`affiliation`</b>:  The relationship the collaborator has with the repository. 
+ - <b>`permission`</b>:  The permission the collaborator has on the repository. 
+ - <b>`repository`</b>:  The repository to get collaborators for. 
+
+
+
+**Returns:**
+ The logins of collaborators that match the criteria. 
+
+
+---
+
+<a href="../repo_policy_compliance/github_client.py#L119"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `get_branch`
+
+```python
+get_branch(
+    github_client: Github,
+    repository_name: str,
+    branch_name: str
+) → Branch
+```
+
+Get the branch for the check. 
+
+
+
+**Args:**
+
+ - <b>`github_client`</b>:  The client to be used for GitHub API interactions. 
+ - <b>`repository_name`</b>:  The name of the repository to run the check on. 
+ - <b>`branch_name`</b>:  The name of the branch to check. 
+
+
+
+**Returns:**
+ The requested branch. 
+
+