Skip to content

Commit 00618bf

Browse files
thekavemanthekaveman
authored
Feat: docs (#61)
2 parents 49c3a3c + 8dbe91f commit 00618bf

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+1319
-246
lines changed

‎.devcontainer/Dockerfile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ COPY compiler_admin compiler_admin
2020
COPY pyproject.toml pyproject.toml
2121
RUN pip install -e .[dev,test]
2222

23+
COPY docs/requirements.txt docs/requirements.txt
24+
RUN pip install -r docs/requirements.txt
25+
2326
USER root
2427
RUN chown -R $USER:$USER /home/$USER
2528
USER $USER

‎.devcontainer/devcontainer.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
"name": "compilerla/admin",
33
"dockerComposeFile": ["../compose.yaml"],
44
"service": "dev",
5+
"runServices": ["dev", "docs"],
6+
"forwardPorts": ["docs:8000"],
57
"workspaceFolder": "/home/compiler/compiler-admin",
68
"postAttachCommand": ["/bin/bash", ".devcontainer/postAttach.sh"],
79
"customizations": {

‎.github/workflows/mkdocs.yml‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
name: Publish docs
2+
on:
3+
workflow_dispatch:
4+
pull_request:
5+
branches:
6+
- main
7+
paths:
8+
- "docs/**"
9+
- "mkdocs.yml"
10+
- ".github/workflows/mkdocs.yml"
11+
push:
12+
branches:
13+
- main
14+
paths:
15+
- ".github/workflows/mkdocs.yml"
16+
- "docs/**"
17+
- ".markdownlint.yaml"
18+
- "mkdocs.yml"
19+
20+
jobs:
21+
docs-preview:
22+
name: Publish docs preview
23+
runs-on: ubuntu-latest
24+
# only pull requests should generate a preview
25+
if: github.event.pull_request
26+
permissions:
27+
pull-requests: write
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
with:
32+
ref: "refs/pull/${{ github.event.number }}/merge"
33+
34+
- name: Setup Python
35+
uses: actions/setup-python@v5
36+
with:
37+
python-version-file: .github/workflows/.python-version
38+
cache: pip
39+
cache-dependency-path: |
40+
"**/pyproject.toml"
41+
"docs/requirements.txt"
42+
43+
- name: Build MkDocs website
44+
run: |
45+
pip install .[dev] -r docs/requirements.txt
46+
mkdocs build
47+
48+
- name: Install Netlify CLI
49+
run: npm install --location=global netlify-cli@17.x.x
50+
51+
- name: Deploy Preview to Netlify
52+
run: |
53+
netlify deploy \
54+
--alias="${GITHUB_REPOSITORY#*/}-${{ github.event.number }}" \
55+
--auth=${{ secrets.NETLIFY_AUTH_TOKEN }} \
56+
--dir="site" \
57+
--site=${{ vars.NETLIFY_PREVIEW_APP_SITE_ID }}
58+
59+
- name: Find existing comment
60+
uses: peter-evans/find-comment@v3
61+
id: find-comment
62+
with:
63+
issue-number: ${{ github.event.number }}
64+
comment-author: "github-actions[bot]"
65+
body-includes: "Preview url: https://"
66+
67+
- name: Add Netlify link PR comment
68+
uses: actions/github-script@v7
69+
if: steps.find-comment.outputs.comment-id == ''
70+
with:
71+
github-token: ${{ secrets.GITHUB_TOKEN }}
72+
script: |
73+
const hostnameSuffix = "compiler-previews.netlify.app"
74+
github.rest.issues.createComment({
75+
issue_number: context.issue.number,
76+
owner: context.repo.owner,
77+
repo: context.repo.repo,
78+
body: `Preview url: https://${context.repo.repo}-${{ github.event.number }}--${hostnameSuffix}`,
79+
})
80+
81+
docs:
82+
name: Publish docs
83+
runs-on: ubuntu-latest
84+
# don't publish for pull requests
85+
if: github.event.pull_request == null
86+
permissions:
87+
contents: write
88+
steps:
89+
- name: Checkout
90+
uses: actions/checkout@v4
91+
92+
- uses: actions/setup-python@v5
93+
with:
94+
python-version-file: .github/workflows/.python-version
95+
cache: pip
96+
cache-dependency-path: |
97+
"**/pyproject.toml"
98+
"docs/requirements.txt"
99+
100+
- name: Install MkDocs requirements
101+
run: |
102+
pip install .[dev] -r docs/requirements.txt
103+
104+
- name: Deploy MkDocs website
105+
run: |
106+
mkdocs gh-deploy --force

‎.markdownlint.yaml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# includes/excludes all rules by default
2+
default: true
3+
4+
# 4-space list indentation works best with MkDocs
5+
MD007:
6+
indent: 4
7+
8+
# Remove line length limit - no one wants to hard wrap all their paragraphs
9+
MD013: false
10+
11+
# Allow inline HTML
12+
MD033: false
13+
14+
# Allow duplicate headers
15+
MD024: false
16+
17+
# Allow mixing code block and fenced code regions
18+
# Useful for pages with admonitions and fenced code blocks
19+
MD046: false

‎README.md‎

Lines changed: 6 additions & 228 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,15 @@
22

33
Automating Compiler's administrative tasks.
44

5-
Built on top of [GAMADV-XTD3](https://github.com/taers232c/GAMADV-XTD3) and [GYB](https://github.com/GAM-team/got-your-back).
5+
Built on top of [GAM7](https://github.com/GAM-team/GAM) and [GYB](https://github.com/GAM-team/got-your-back).
66

77
**Note:** This tool can only be used by those with administrator access to Compiler's Google Workspace.
88

9-
## Usage
9+
## Documentation
10+
11+
For full installation, usage, and command reference, please see the [docs site](https://docs.compiler.la/compiler-admin).
12+
13+
## Basic Usage
1014

1115
```bash
1216
$ compiler-admin -h
@@ -24,229 +28,3 @@ options:
2428
-h, --help show this help message and exit
2529
-v, --version show program's version number and exit
2630
```
27-
28-
## Getting started
29-
30-
```bash
31-
mkdir -p ~/.config/compiler-admin
32-
33-
git clone https://github.com/compilerla/compiler-admin.git
34-
35-
cd compiler-admin
36-
```
37-
38-
Now open in VS Code, and when prompted, reopen in the devcontainer.
39-
40-
## Initial setup
41-
42-
Initial setup of a GAMADV-XTD3 project and GYB project is required to provide necessary API access to the Google Workspace.
43-
44-
```bash
45-
$ compiler-admin init -h
46-
usage: compiler-admin init [-h] [--gam] [--gyb] username
47-
48-
positional arguments:
49-
username A Compiler user account name, sans domain.
50-
51-
options:
52-
-h, --help show this help message and exit
53-
--gam If provided, initialize a new GAM project.
54-
--gyb If provided, initialize a new GYB project.
55-
```
56-
57-
The `init` commands follows the steps in the [GAMADV-XTD3 Wiki](https://github.com/taers232c/GAMADV-XTD3/wiki/#requirements).
58-
59-
Additionally, GYB is used for Gmail backup/restore. See the [GYB Wiki](https://github.com/GAM-team/got-your-back/wiki) for more information.
60-
61-
## Working with time entires
62-
63-
The `time` command provides an interface for working with time entries from Compiler's various systems:
64-
65-
```bash
66-
$ compiler-admin time --help
67-
Usage: compiler-admin time [OPTIONS] COMMAND [ARGS]...
68-
69-
Work with Compiler time entries.
70-
71-
Options:
72-
--help Show this message and exit.
73-
74-
Commands:
75-
convert Convert a time report from one format into another.
76-
download Download a Toggl time report in CSV format.
77-
lock Lock Toggl time entries.
78-
verify Verify time entry CSV files.
79-
```
80-
81-
### Locking time entries
82-
83-
Use this command to lock Toggl time entries up to some date (defaulting to the last day of the prior month).
84-
85-
```bash
86-
$ compiler-admin time lock --help
87-
Usage: compiler-admin time lock [OPTIONS]
88-
89-
Lock Toggl time entries.
90-
91-
Options:
92-
--date TEXT The date to lock time entries, formatted as YYYY-MM-DD.
93-
Defaults to the last day of the previous month.
94-
--help Show this message and exit.
95-
```
96-
97-
### Downloading a Toggl report
98-
99-
Use this command to download a time report from Toggl in CSV format (defaulting to the prior month):
100-
101-
```bash
102-
$ compiler-admin time download --help
103-
Usage: compiler-admin time download [OPTIONS]
104-
105-
Download a Toggl time report in CSV format.
106-
107-
Options:
108-
--start YYYY-MM-DD The start date of the reporting period. Defaults
109-
to the beginning of the prior month.
110-
--end YYYY-MM-DD The end date of the reporting period. Defaults to
111-
the end of the prior month.
112-
--output TEXT The path to the file where downloaded data should
113-
be written. Defaults to a path calculated from the
114-
date range.
115-
--all Download all time entries. The default is to
116-
download only billable time entries.
117-
-c, --client CLIENT_ID An ID for a Toggl Client to filter for in reports.
118-
Can be supplied more than once.
119-
-p, --project PROJECT_ID An ID for a Toggl Project to filter for in
120-
reports. Can be supplied more than once.
121-
-t, --task TASK_ID An ID for a Toggl Project Task to filter for in
122-
reports. Can be supplied more than once.
123-
-u, --user USER_ID An ID for a Toggl User to filter for in reports.
124-
Can be supplied more than once.
125-
--help Show this message and exit.
126-
```
127-
128-
### Converting an hours report
129-
130-
With a CSV exported from either Harvest or Toggl, use this command to convert to the opposite format:
131-
132-
```bash
133-
$ compiler-admin time convert --help
134-
Usage: compiler-admin time convert [OPTIONS]
135-
136-
Convert a time report from one format into another.
137-
138-
Options:
139-
--input TEXT The path to the source data for conversion.
140-
Defaults to $TOGGL_DATA or stdin.
141-
--output TEXT The path to the file where converted data
142-
should be written. Defaults to $HARVEST_DATA
143-
or stdout.
144-
--from [harvest|toggl] The format of the source data. [default:
145-
toggl]
146-
--to [harvest|justworks|toggl] The format of the converted data. [default:
147-
harvest]
148-
--client TEXT The name of the client to use in converted
149-
data.
150-
--help Show this message and exit.
151-
```
152-
153-
### Verifying an hours conversion
154-
155-
```bash
156-
$ compiler-admin time verify --help
157-
Usage: compiler-admin time verify [OPTIONS] [FILES]...
158-
159-
Verify time entry CSV files.
160-
161-
Options:
162-
--help Show this message and exit.
163-
```
164-
165-
## Working with users
166-
167-
The following commands are available to work with users in the Compiler domain:
168-
169-
```bash
170-
$ compiler-admin user -h
171-
usage: compiler-admin user [-h] {alumni,create,convert,delete,offboard,reset,restore,signout} ...
172-
173-
positional arguments:
174-
{alumni,create,convert,delete,offboard,reset,restore,signout}
175-
The user command to run.
176-
alumni Convert a user account to a Compiler alumni.
177-
create Create a new user in the Compiler domain.
178-
convert Convert a user account to a new type.
179-
delete Delete a user account.
180-
offboard Offboard a user account.
181-
reset Reset a user's password to a randomly generated string.
182-
restore Restore an email backup from a prior offboarding.
183-
signout Signs a user out from all active sessions.
184-
185-
options:
186-
-h, --help show this help message and exit
187-
```
188-
189-
### Creating a user
190-
191-
```bash
192-
$ compiler-admin user create -h
193-
usage: compiler-admin user create [-h] [--notify NOTIFY] username
194-
195-
positional arguments:
196-
username A Compiler user account name, sans domain.
197-
198-
options:
199-
-h, --help show this help message and exit
200-
--notify NOTIFY An email address to send the newly created account info.
201-
```
202-
203-
Additional options are passed through to GAM, see more about [GAM user create](https://github.com/taers232c/GAMADV-XTD3/wiki/Users#create-a-user)
204-
205-
### Convert a user
206-
207-
```bash
208-
$ compiler-admin user convert -h
209-
usage: compiler-admin user convert [-h] [--force] [--notify NOTIFY] username {alumni,contractor,partner,staff}
210-
211-
positional arguments:
212-
username A Compiler user account name, sans domain.
213-
{alumni,contractor,partner,staff}
214-
Target account type for this conversion.
215-
216-
options:
217-
-h, --help show this help message and exit
218-
--force Don't ask for confirmation before conversion.
219-
--notify NOTIFY An email address to send the alumni's new password.
220-
```
221-
222-
### Offboarding a user
223-
224-
```bash
225-
$ compiler-admin user offboard -h
226-
usage: compiler-admin user offboard [-h] [--alias ALIAS] [--force] username
227-
228-
positional arguments:
229-
username A Compiler user account name, sans domain.
230-
231-
options:
232-
-h, --help show this help message and exit
233-
--alias ALIAS Account to assign username as an alias.
234-
--force Don't ask for confirmation before offboarding.
235-
```
236-
237-
This script creates a local backup of `USER`'s inbox, see [Restore](#restore-an-email-backup)
238-
239-
### Restore an email backup
240-
241-
Retore a backup from a prior [Offboarding](#offboarding-a-user) into the `archive@compiler.la` account.
242-
243-
```bash
244-
$ compiler-admin user restore -h
245-
usage: compiler-admin user restore [-h] username
246-
247-
positional arguments:
248-
username The user's account name, sans domain.
249-
250-
options:
251-
-h, --help show this help message and exit
252-
```

0 commit comments

Comments
 (0)