Skip to content

Commit aa09d12

Browse files
KamforkaKamforka
committed
#345 - Add initial mkdocs page
1 parent aecec9e commit aa09d12

File tree

12 files changed

+257
-35
lines changed

12 files changed

+257
-35
lines changed

‎.github/workflows/_build-docs.yml

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: build-docs
2+
on:
3+
workflow_call:
4+
jobs:
5+
build:
6+
name: Build docs
7+
runs-on: ubuntu-latest
8+
steps:
9+
- uses: actions/checkout@v4
10+
- name: Set up Python
11+
uses: actions/setup-python@v4
12+
with:
13+
python-version: 3.12
14+
- name: Install build dependencies
15+
run: pip install --no-cache-dir -U pip .['docs']
16+
- name: Build docs
17+
run: ./scripts/cd.py --build-docs

‎.github/workflows/_deploy-docs.yml

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
name: deploy-docs
2+
on:
3+
workflow_call:
4+
jobs:
5+
upload:
6+
name: Deploy docs to github pages
7+
runs-on: ubuntu-latest
8+
steps:
9+
- uses: actions/checkout@v4
10+
- name: Compare tag and package version
11+
run: |
12+
TAG=${GITHUB_REF#refs/*/}
13+
VERSION=$(grep -Po '(?<=version = ")[^"]*' pyproject.toml)
14+
if [ "$TAG" != "$VERSION" ]; then
15+
echo "Tag value and package version are different: ${TAG} != ${VERSION}"
16+
exit 1
17+
fi
18+
- name: Set up Python
19+
uses: actions/setup-python@v4
20+
with:
21+
python-version: 3.12
22+
- name: Install build dependencies
23+
run: pip install --no-cache-dir -U pip .['docs']
24+
- name: Deploy to github pages
25+
run: ./scripts/cd.py --deploy-docs

‎.github/workflows/main-cicd.yml

+6-1
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,14 @@ jobs:
1616
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
1717
build-package:
1818
uses: ./.github/workflows/_build-package.yml
19+
build-docs:
20+
uses: ./.github/workflows/_build-docs.yml
1921
upload-package:
2022
uses: ./.github/workflows/_upload-package.yml
2123
if: startsWith(github.ref, 'refs/tags/')
22-
needs: [static-checks, integration-tests, build-package]
24+
needs: [static-checks, integration-tests, build-package, build-docs]
2325
secrets:
2426
PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
27+
deploy-docs:
28+
uses: ./.github/workflows/_deploy-docs.yml
29+
needs: [upload-package]

‎.gitignore

+10-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
1+
# generic
12
__pycache__/
23
thehive4py.egg-info/
34
build/
45
dist/
5-
venv/
6-
tmp/
76

8-
# local garbage yet
9-
tests/resources/
10-
examples/
7+
# pytest
8+
.coverage
9+
coverage.xml
10+
11+
# mkdocs
12+
site/
13+
14+
# misc
15+
tmp/

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2023 StrangeBee
3+
Copyright (c) 2024 StrangeBee
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,11 @@
55
<em>thehive4py - the de facto Python API client of <a href="https://strangebee.com/thehive/">TheHive</a></em>
66
</p>
77
<p align="center">
8+
<a href="https://github.com/TheHive-Project/TheHive4py/releases" target="_blank">
9+
<img src="https://img.shields.io/github/v/release/Thehive-project/thehive4py?logo=github&logoColor=FFC72C&labelColor=0049D4" alt="release">
10+
</a>
811
<a href="https://github.com/TheHive-Project/TheHive4py/actions/workflows/main-cicd.yml" target="_blank">
9-
<img src="https://img.shields.io/github/actions/workflow/status/TheHive-Project/TheHive4py/main-cicd.yml?logo=github&logoColor=FFC72C&labelColor=0049D4" alt="cicd">
12+
<img src="https://img.shields.io/github/actions/workflow/status/TheHive-Project/TheHive4py/main-cicd.yml?logo=github&logoColor=FFC72C&labelColor=0049D4" alt="build">
1013
</a>
1114
<a href="https://app.codecov.io/github/TheHive-Project/TheHive4py" target="_blank">
1215
<img src="https://img.shields.io/codecov/c/gh/TheHive-Project/TheHive4py?logo=codecov&logoColor=FFC72C&labelColor=0049D4" alt="codecov">

‎docs/img/strangebee.png

7.88 KB
Loading

‎docs/index.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Coming Soon!
3+
hide:
4+
- toc
5+
- navigation
6+
---
7+
#
8+
<div markdown align="center">
9+
<p>
10+
<b style="display: block; font-size: 2rem">TheHive4py</b>
11+
<a href="https://github.com/TheHive-Project/TheHive4py" target="_blank">
12+
<img src="https://strangebee.com/wp-content/uploads/2024/07/Icon4Nav_TheHive.png" alt="TheHive Logo">
13+
</a>
14+
</p>
15+
<p markdown>
16+
:material-bee:{ .strangebee .bluebee .upleftbee }
17+
:material-bee:{ .strangebee .yellowbee .upbee }
18+
:material-bee:{ .strangebee .bluebee .uprightbee }
19+
</p>
20+
<span class="coming-soon">Coming Soon!</span>
21+
<p markdown>
22+
:material-bee:{ .strangebee .yellowbee .downleftbee }
23+
:material-bee:{ .strangebee .bluebee .downbee }
24+
:material-bee:{ .strangebee .yellowbee .downrightbee }
25+
</p>
26+
27+
28+
29+
<p><em>Our bees are out buzzing to gather all the docs you need!</em></p>
30+
<p><em>Check out our <a href="https://github.com/TheHive-Project/TheHive4py?tab=readme-ov-file#quickstart" target="_blank">Quickstart</a> in the meantime!<em></p>
31+
</div>
32+
33+

‎docs/styles/extra.css

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
:root {
2+
--md-primary-fg-color: #0049d4;
3+
--md-accent-fg-color: #ffc72c;
4+
}
5+
6+
@keyframes pulse {
7+
0%, 100% {
8+
transform: scale(1);
9+
}
10+
50% {
11+
transform: scale(1.25);
12+
}
13+
}
14+
15+
16+
.coming-soon {
17+
color: var(--md-primary-fg-color);
18+
font-size: 1.5rem;
19+
font-weight: bold;
20+
transition: 0.75s;
21+
}
22+
23+
.coming-soon:hover{
24+
color: var(--md-accent-fg-color);
25+
transition: 0.75s;
26+
}
27+
28+
.upleftbee {
29+
rotate: -90deg;
30+
}
31+
32+
.upbee {
33+
rotate: -45deg;
34+
}
35+
36+
.uprightbee{
37+
rotate: 0deg;
38+
}
39+
40+
.downleftbee {
41+
rotate: 180deg;
42+
}
43+
44+
.downbee {
45+
rotate: 135deg;
46+
}
47+
48+
.downrightbee{
49+
rotate: 90deg;
50+
}
51+
52+
.yellowbee {
53+
color: var(--md-accent-fg-color)
54+
}
55+
56+
.bluebee {
57+
color: var(--md-primary-fg-color)
58+
}
59+
60+
.strangebee {
61+
animation: pulse 2s infinite;
62+
font-size: 1.5rem;
63+
vertical-align: top !important;
64+
}

‎mkdocs.yml

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
site_name: TheHive4py
2+
theme:
3+
name: material
4+
favicon: img/strangebee.png
5+
logo: img/strangebee.png
6+
features:
7+
- navigation.footer
8+
palette:
9+
- media: "(prefers-color-scheme)"
10+
toggle:
11+
icon: material/lightbulb-auto
12+
name: Switch to light mode
13+
- media: '(prefers-color-scheme: light)'
14+
scheme: default
15+
primary: custom
16+
accent: custom
17+
toggle:
18+
icon: material/lightbulb
19+
name: Switch to dark mode
20+
- media: '(prefers-color-scheme: dark)'
21+
scheme: slate
22+
primary: custom
23+
accent: custom
24+
toggle:
25+
icon: material/lightbulb-outline
26+
name: Switch to system preference
27+
extra_css:
28+
- styles/extra.css
29+
repo_name: TheHive-Project/TheHive4py
30+
repo_url: https://github.com/TheHive-Project/TheHive4py
31+
markdown_extensions:
32+
- attr_list
33+
- md_in_html
34+
- pymdownx.emoji:
35+
emoji_index: !!python/name:material.extensions.emoji.twemoji
36+
emoji_generator: !!python/name:material.extensions.emoji.to_svg
37+
extra:
38+
social:
39+
- icon: simple/discord
40+
link: https://discord.com/invite/XhxG3vzM44
41+
name: Discord
42+
- icon: simple/github
43+
link: https://github.com/TheHive-Project/TheHive4py
44+
name: GitHub
45+
- icon: simple/python
46+
link: https://pypi.org/project/thehive4py/
47+
name: PyPI
48+
49+

‎pyproject.toml

+1
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ authors = [{ name = "Szabolcs Antal", email = "[email protected]" }]
2828
[project.optional-dependencies]
2929
audit = ["bandit", "pip-audit"]
3030
build = ["build", "twine"]
31+
docs = ["mkdocs", "mkdocs-material"]
3132
lint = ["black", "flake8-pyproject", "mypy", "pre-commit"]
3233
test = ["pytest", "pytest-cov"]
3334
dev = ["thehive4py[audit, lint, test, build]"]

‎scripts/cd.py

+47-27
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
#!/usr/bin/env python
22
import argparse
33
import subprocess
4-
from typing import List
4+
from typing import Dict
55

66

77
def _run_subprocess(
@@ -23,13 +23,6 @@ def _run_subprocess(
2323
exit(err.returncode)
2424

2525

26-
def run_all(quiet=False):
27-
print("Run all deployment tasks...")
28-
run_build(quiet=quiet)
29-
run_upload(quiet=quiet)
30-
print("All tasks succeeded!")
31-
32-
3326
def run_build(quiet: bool):
3427
print("Building thehive4py with the build module...")
3528
_run_subprocess(
@@ -52,14 +45,34 @@ def run_upload(quiet: bool):
5245
print("Successfully published thehive4py!")
5346

5447

55-
def build_run_options() -> List[dict]:
56-
return [
57-
{"name": "build", "help": "run build step", "func": run_build},
58-
{"name": "upload", "help": "run upload step", "func": run_upload},
59-
]
48+
def run_build_docs(quiet: bool):
49+
print("Building thehive4py docs...")
50+
_run_subprocess(
51+
command="mkdocs build --clean --strict",
52+
quiet=quiet,
53+
)
54+
print("Successfully built thehive4py docs!")
6055

6156

62-
def parse_arguments(run_options: List[dict]):
57+
def run_deploy_docs(quiet: bool):
58+
print("Deploying thehive4py docs to gh-pages...")
59+
_run_subprocess(
60+
command="mkdocs gh-deploy --force",
61+
quiet=quiet,
62+
)
63+
print("Successfully deployed thehive4py docs to gh-pages!")
64+
65+
66+
def build_run_options() -> Dict[str, dict]:
67+
return {
68+
"build": {"help": "build the package locally", "func": run_build},
69+
"upload": {"help": "upload the package to pypi", "func": run_upload},
70+
"build-docs": {"help": "build the docs locally", "func": run_build_docs},
71+
"deploy-docs": {"help": "deploy the docs to gh-pages", "func": run_deploy_docs},
72+
}
73+
74+
75+
def parse_arguments(run_options: Dict[str, dict]):
6376
parser = argparse.ArgumentParser(
6477
prog="thehive4py-cd",
6578
description="run all cd steps or use options to run cd steps selectively",
@@ -72,14 +85,21 @@ def parse_arguments(run_options: List[dict]):
7285
help="silence verbose output",
7386
)
7487

75-
for run_option in run_options:
88+
for run_option_name, run_option_attributes in run_options.items():
7689
parser.add_argument(
77-
f"--{run_option['name']}",
78-
help=run_option["help"],
90+
f"--{run_option_name.replace('_', '-')}",
91+
help=run_option_attributes["help"],
7992
action="store_true",
8093
)
8194

82-
return parser.parse_args()
95+
args = parser.parse_args()
96+
97+
if not any(
98+
getattr(args, run_option.replace("-", "_")) for run_option in run_options
99+
):
100+
parser.error(f"provide at least one option from: {list(run_options)}")
101+
102+
return args
83103

84104

85105
def main():
@@ -88,17 +108,17 @@ def main():
88108

89109
quiet = args.quiet
90110

91-
selective_runs = [
92-
run_option["func"]
93-
for run_option in run_options
94-
if getattr(args, run_option["name"])
111+
selected_run_funcs = [
112+
run_option_attributes["func"]
113+
for run_option_name, run_option_attributes in run_options.items()
114+
if getattr(args, run_option_name.replace("-", "_"))
95115
]
96116

97-
if selective_runs:
98-
for run in selective_runs:
99-
run(quiet=quiet)
100-
else:
101-
run_all(quiet=quiet)
117+
for run_func in selected_run_funcs:
118+
run_func(quiet=quiet)
119+
print()
120+
121+
print("Done!")
102122

103123

104124
if __name__ == "__main__":

0 commit comments

Comments
 (0)