Skip to content

Commit 907df64

Browse files
jdkanderssoncbartz
jdkandersson
and
cbartz
authored
add PR checklist and generate source docs (#207)
* add PR checklist and generate source docs * Update CONTRIBUTING.md Co-authored-by: Christopher Bartz <[email protected]> --------- Co-authored-by: Christopher Bartz <[email protected]>
1 parent 9674fdc commit 907df64

39 files changed

+2444
-56
lines changed

‎.github/pull_request_template.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Applicable spec: <link>
2+
3+
### Overview
4+
5+
<!-- A high level overview of the change -->
6+
7+
### Rationale
8+
9+
<!-- The reason the change is needed -->
10+
11+
### Module Changes
12+
13+
<!-- Any high level changes to modules and why (Service, Observer, helper) -->
14+
15+
### Checklist
16+
17+
- [ ] The [contributing guide](https://github.com/canonical/is-charms-contributing-guide) was applied
18+
- [ ] The documentation is generated using `src-docs`
19+
- [ ] The PR is tagged with appropriate label (`urgent`, `trivial`, `complex`)
20+
21+
<!-- Explanation for any unchecked items above -->

‎CONTRIBUTING.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## Generating src docs for every commit
2+
3+
Run the following command:
4+
5+
```bash
6+
echo -e "tox -e src-docs\ngit add src-docs\n" >> .git/hooks/pre-commit
7+
chmod +x .git/hooks/pre-commit
8+
```

‎README.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Upload Charm Documentation
22

3-
*This action is still in alpha, breaking changes could occur.*
3+
*This action is still in alpha, breaking changes could occur. For now, it should
4+
only be used on Canonical repositories after approval.*
45

56
This action automates uploading documentation from the `docs` folder in a
67
repository to discourse which is how the charm documentation is published to

‎generate-src-docs.sh

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#!/usr/bin/env bash
2+
3+
# Copyright 2023 Canonical Ltd.
4+
# See LICENSE file for licensing details.
5+
6+
rm -rf src-docs
7+
lazydocs --no-watermark --output-path src-docs src/*.py

‎src-docs/__init__.py.md

+101
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
<!-- markdownlint-disable -->
2+
3+
<a href="../src/__init__.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
4+
5+
# <kbd>module</kbd> `__init__.py`
6+
Library for uploading docs to charmhub.
7+
8+
**Global Variables**
9+
---------------
10+
- **DRY_RUN_NAVLINK_LINK**
11+
- **FAIL_NAVLINK_LINK**
12+
- **DOCUMENTATION_FOLDER_NAME**
13+
- **DOCUMENTATION_TAG**
14+
- **DEFAULT_BRANCH_NAME**
15+
- **GETTING_STARTED**
16+
17+
---
18+
19+
<a href="../src/__init__.py#L33"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
20+
21+
## <kbd>function</kbd> `run_reconcile`
22+
23+
```python
24+
run_reconcile(
25+
clients: Clients,
26+
user_inputs: UserInputs
27+
) → ReconcileOutputs | None
28+
```
29+
30+
Upload the documentation to charmhub.
31+
32+
33+
34+
**Args:**
35+
36+
- <b>`clients`</b>: The clients to interact with things like discourse and the repository.
37+
- <b>`user_inputs`</b>: Configurable inputs for running upload-charm-docs.
38+
39+
40+
41+
**Returns:**
42+
ReconcileOutputs object with the result of the action. None, if there is no reconcile.
43+
44+
45+
46+
**Raises:**
47+
48+
- <b>`InputError`</b>: if there are any problems with executing any of the actions.
49+
- <b>`TaggingNotAllowedError`</b>: if the reconcile tries to tag a branch which is not the main base branch
50+
51+
52+
---
53+
54+
<a href="../src/__init__.py#L133"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
55+
56+
## <kbd>function</kbd> `run_migrate`
57+
58+
```python
59+
run_migrate(clients: Clients, user_inputs: UserInputs) → MigrateOutputs | None
60+
```
61+
62+
Migrate existing docs from charmhub to local repository.
63+
64+
65+
66+
**Args:**
67+
68+
- <b>`clients`</b>: The clients to interact with things like discourse and the repository.
69+
- <b>`user_inputs`</b>: Configurable inputs for running upload-charm-docs.
70+
71+
72+
73+
**Returns:**
74+
MigrateOutputs providing details on the action performed and a link to the Pull Request containing migrated documentation. None if there is no migration.
75+
76+
77+
---
78+
79+
<a href="../src/__init__.py#L189"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
80+
81+
## <kbd>function</kbd> `pre_flight_checks`
82+
83+
```python
84+
pre_flight_checks(clients: Clients, user_inputs: UserInputs) → bool
85+
```
86+
87+
Perform checks to make sure the repository is in a consistent state.
88+
89+
90+
91+
**Args:**
92+
93+
- <b>`clients`</b>: The clients to interact with things like discourse and the repository.
94+
- <b>`user_inputs`</b>: Configurable inputs for running upload-charm-docs.
95+
96+
97+
98+
**Returns:**
99+
Boolean representing whether the checks have all been passed.
100+
101+

‎src-docs/action.py.md

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
<!-- markdownlint-disable -->
2+
3+
<a href="../src/action.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
4+
5+
# <kbd>module</kbd> `action.py`
6+
Module for taking the required actions to match the server state with the local state.
7+
8+
**Global Variables**
9+
---------------
10+
- **DRY_RUN_NAVLINK_LINK**
11+
- **DRY_RUN_REASON**
12+
- **BASE_MISSING_REASON**
13+
- **FAIL_NAVLINK_LINK**
14+
- **NOT_DELETE_REASON**
15+
16+
---
17+
18+
<a href="../src/action.py#L416"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
19+
20+
## <kbd>function</kbd> `run_all`
21+
22+
```python
23+
run_all(
24+
actions: Iterable[CreateAction | NoopAction | UpdateAction | DeleteAction],
25+
index: Index,
26+
discourse: Discourse,
27+
dry_run: bool,
28+
delete_pages: bool
29+
) → tuple[str, list[ActionReport]]
30+
```
31+
32+
Take the actions against the server.
33+
34+
35+
36+
**Args:**
37+
38+
- <b>`actions`</b>: The actions to take.
39+
- <b>`index`</b>: Information about the index.
40+
- <b>`discourse`</b>: A client to the documentation server.
41+
- <b>`dry_run`</b>: If enabled, only log the action that would be taken.
42+
- <b>`delete_pages`</b>: Whether to delete pages that are no longer needed.
43+
44+
45+
46+
**Returns:**
47+
A 2-element tuple with the index url and the reports of all the requested action.
48+
49+
50+
---
51+
52+
## <kbd>class</kbd> `UpdateCase`
53+
The possible cases for the update action.
54+
55+
Attrs: INVALID: The action is not valid. DRY_RUN: Do not make any changes. CONTENT_CHANGE: The content has been changed. BASE_MISSING: The base content is not available. DEFAULT: No other specific case applies.
56+
57+
58+
59+
60+

‎src-docs/check.py.md

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
<!-- markdownlint-disable -->
2+
3+
<a href="../src/check.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
4+
5+
# <kbd>module</kbd> `check.py`
6+
Module for running checks.
7+
8+
**Global Variables**
9+
---------------
10+
- **DOCUMENTATION_TAG**
11+
12+
---
13+
14+
<a href="../src/check.py#L45"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
15+
16+
## <kbd>function</kbd> `get_path_with_diffs`
17+
18+
```python
19+
get_path_with_diffs(actions: Iterable[UpdateAction]) → PathsWithDiff
20+
```
21+
22+
Generate the paths that have either local or server content changes.
23+
24+
25+
26+
**Args:**
27+
28+
- <b>`actions`</b>: The update actions to track diffs for.
29+
30+
31+
32+
**Returns:**
33+
The paths that have differences.
34+
35+
36+
---
37+
38+
<a href="../src/check.py#L151"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
39+
40+
## <kbd>function</kbd> `conflicts`
41+
42+
```python
43+
conflicts(
44+
actions: Iterable[CreateAction | NoopAction | UpdateAction | DeleteAction],
45+
repository: Client,
46+
user_inputs: UserInputs
47+
) → Iterator[Problem]
48+
```
49+
50+
Check whether actions have any content conflicts.
51+
52+
There are two types of conflicts. The first is where the local content is different to what is on the server and both the local content and the server content is different from the base. This means that there were edits on the server which have not been merged into git and the PR is making changes to the same page.
53+
54+
The second type of conflict is a logical conflict which arises out of that there are at least some changes on the server that have not been merged into git yet and the branch is proposing to make changes to the documentation as well. This means that there could be changes made on the server which logically conflict with proposed changes in the PR. These conflicts can be supppressed using the discourse-ahead-ok tag on the commit that the action is running on.
55+
56+
57+
58+
**Args:**
59+
60+
- <b>`actions`</b>: The actions to check.
61+
- <b>`repository`</b>: Client for repository interactions.
62+
- <b>`user_inputs`</b>: Configuration from the user.
63+
64+
65+
66+
**Yields:**
67+
A problem for each action with a conflict
68+
69+
70+
---
71+
72+
## <kbd>class</kbd> `PathsWithDiff`
73+
Keeps track of paths that have any differences.
74+
75+
Attrs: base_local_diffs: The paths that have a difference between the base and local content. base_server_diffs: The paths that have a difference between the local and server content.
76+
77+
78+
79+
80+
81+
---
82+
83+
## <kbd>class</kbd> `Problem`
84+
Details about a failed check.
85+
86+
Attrs: path: Unique identifier for the file and discourse topic with the problem description: A summary of what the problem is and how to resolve it.
87+
88+
89+
90+
91+

‎src-docs/clients.py.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<!-- markdownlint-disable -->
2+
3+
<a href="../src/clients.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
4+
5+
# <kbd>module</kbd> `clients.py`
6+
Module for Client class.
7+
8+
9+
---
10+
11+
<a href="../src/clients.py#L27"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
12+
13+
## <kbd>function</kbd> `get_clients`
14+
15+
```python
16+
get_clients(user_inputs: UserInputs, base_path: Path) → Clients
17+
```
18+
19+
Return Clients object.
20+
21+
22+
23+
**Args:**
24+
25+
- <b>`user_inputs`</b>: inputs provided via environment
26+
- <b>`base_path`</b>: path where the git repository is stored
27+
28+
29+
30+
**Returns:**
31+
Clients object embedding both Discourse API and Repository clients
32+
33+
34+
---
35+
36+
## <kbd>class</kbd> `Clients`
37+
Collection of clients needed during execution.
38+
39+
Attrs: discourse: Discourse client. repository: Client for the repository.
40+
41+
42+
43+
44+

0 commit comments

Comments
 (0)