Skip to content

Commit 125afd0

Browse files
DonAsakoDonAsako
committed
docs: add mkdocs + github page
1 parent 6af39f9 commit 125afd0

13 files changed

Lines changed: 865 additions & 30 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
name: docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- docs/**
9+
- mkdocs.yml
10+
- requirements/docs.txt
11+
- .github/workflows/docs.yml
12+
13+
# Allow the workflow to publish to GitHub Pages.
14+
permissions:
15+
contents: read
16+
pages: write
17+
id-token: write
18+
19+
# Never run two deployments at once; let the latest finish.
20+
concurrency:
21+
group: pages
22+
cancel-in-progress: false
23+
24+
jobs:
25+
build:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- uses: actions/checkout@v4
29+
30+
- uses: actions/setup-python@v5
31+
with:
32+
python-version-file: .python-version
33+
cache: pip
34+
35+
- name: Install MkDocs
36+
run: pip install -r requirements/docs.txt
37+
38+
- name: Build site
39+
run: mkdocs build --strict
40+
41+
- uses: actions/upload-pages-artifact@v3
42+
with:
43+
path: site
44+
45+
deploy:
46+
needs: build
47+
runs-on: ubuntu-latest
48+
environment:
49+
name: github-pages
50+
url: ${{ steps.deployment.outputs.page_url }}
51+
steps:
52+
- name: Deploy to GitHub Pages
53+
id: deployment
54+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,3 +173,6 @@ cython_debug/
173173

174174
# PyPI configuration file
175175
.pypirc
176+
177+
# MkDocs build output
178+
/site/

‎CONTRIBUTING.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,82 @@ cd Eskoz
2929
4. **Submit a pull request** with a clear description of your changes.
3030
- For non-trivial changes, please open an [issue](https://github.com/DonAsako/Eskoz/issues) first and reference it in your PR.
3131

32+
## Commit Convention
33+
34+
Eskoz uses [Conventional Commits](https://www.conventionalcommits.org/). The commit
35+
message **prefix drives automated versioning and the changelog**, so it matters:
36+
37+
| Prefix | Meaning | Version bump |
38+
| ----------- | -------------------------------- | ------------ |
39+
| `feat:` | A new feature | minor |
40+
| `fix:` | A bug fix | patch |
41+
| `perf:` | A performance improvement | patch |
42+
| `refactor:` | Code change, no behaviour change | patch |
43+
| `docs:` | Documentation only | none |
44+
| `chore:` | Tooling, deps, housekeeping | none |
45+
46+
A breaking change is marked with `!` (e.g. `feat!: ...`) or a `BREAKING CHANGE:`
47+
footer, and triggers a **major** bump.
48+
49+
```
50+
feat(blog): add scheduled publishing
51+
fix(admin): handle anonymous user on the dashboard
52+
```
53+
54+
Commit messages are linted by `gitlint` (via a `commit-msg` hook), so a malformed
55+
message is rejected before it lands.
56+
57+
## Local Quality Checks
58+
59+
Quality is enforced by [pre-commit](https://pre-commit.com/). Install the hooks once,
60+
then they run automatically on every commit:
61+
62+
```bash
63+
pip install -r requirements/development.txt
64+
pre-commit install # installs both pre-commit and commit-msg hooks
65+
pre-commit run --all-files # run everything on demand
66+
```
67+
68+
The hooks cover Ruff (lint + format), djLint, yamllint, gitleaks (secret scanning),
69+
gitlint, and `manage.py check` / migration checks.
70+
71+
## Running Tests
72+
73+
Tests are plain Django `TestCase`s under each app's `tests.py`. Locally they run on
74+
SQLite via the development settings:
75+
76+
```bash
77+
export DJANGO_SETTINGS_MODULE=eskoz.settings.development
78+
export DJANGO_SECRET_KEY=dev-dummy-key
79+
python manage.py test apps.analytics apps.blog apps.core apps.education apps.infosec -t .
80+
```
81+
82+
> The `-t .` flag sets the test discovery top-level directory to the repo root so the
83+
> `apps.*.models` packages import under their real dotted path.
84+
85+
In CI, the same suite runs against **PostgreSQL** using `eskoz.settings.ci`, to match
86+
production.
87+
88+
## Continuous Integration & Releases
89+
90+
Everything from a merge to a published release is automated:
91+
92+
1. **On every pull request and push to `main`**, the `CI` workflow runs:
93+
- **quality** — the full pre-commit suite;
94+
- **tests** — the Django test suite against PostgreSQL.
95+
96+
2. **Versioning is handled by [release-please](https://github.com/googleapis/release-please).**
97+
It does **not** release on every push. Instead, it reads the conventional commits
98+
since the last release and opens (or updates) a **release pull request** containing
99+
the version bump and the generated `CHANGELOG.md` entry.
100+
101+
3. **Merging that release PR** is the only thing that cuts a version. It creates the
102+
git tag, the GitHub Release, bumps `eskoz/__init__.py`, and **builds and pushes the
103+
Docker image to GHCR** (`ghcr.io/donasako/eskoz`, tagged `latest`, `vX.Y.Z`, `X.Y`).
104+
105+
A regular (or even force) push to `main` therefore never changes the version on its own
106+
— only merging the release PR does.
107+
32108
## Code of Conduct
33109

34110
Please see our [Code of Conduct](.github/CODE_OF_CONDUCT.md) for guidelines on participating in the Eskoz community. By contributing, you agree to follow these rules to help maintain a welcoming and productive environment.

‎README.md‎

Lines changed: 19 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,14 @@
11
# Eskoz
22

3+
[![CI](https://github.com/DonAsako/eskoz/actions/workflows/ci.yml/badge.svg)](https://github.com/DonAsako/eskoz/actions/workflows/ci.yml)
4+
[![Latest release](https://img.shields.io/github/v/release/DonAsako/eskoz)](https://github.com/DonAsako/eskoz/releases)
5+
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)
6+
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://donasako.github.io/eskoz/)
7+
38
**Eskoz** is a Django-based project designed to help you quickly and easily create a multilingual blog, with a straightforward deployment process.
49

10+
📖 **Full documentation: [donasako.github.io/eskoz](https://donasako.github.io/eskoz/)** — installation, configuration, Docker & bare-metal deployment, theming.
11+
512
## Requirements
613
Make sure you have the following installed on your system:
714
- Docker
@@ -45,6 +52,12 @@ EMAIL= # Email address used for SSL certificate
4552
docker compose -f docker/docker-compose.yml up --build -d
4653
```
4754

55+
> **Prebuilt image:** every release is automatically published to the GitHub
56+
> Container Registry. Instead of building locally, you can pull a tagged image:
57+
> ```sh
58+
> docker pull ghcr.io/donasako/eskoz:latest # or a specific version, e.g. :v0.6.0
59+
> ```
60+
4861
### 2. Create the first admin user
4962
To create the first Django superuser, run:
5063
```sh
@@ -107,43 +120,19 @@ docker compose up --build -d
107120
```
108121
Your new theme should now be applied and visible on the site.
109122

110-
## To-do
111-
### Logs
112-
- [ ] Add Django logging configuration
113-
- [ ] Set up log rotation (e.g. RotatingFileHandler)
114-
- [ ] Mount Docker volume for log files
115-
- [ ] Define log levels (INFO, WARNING, ERROR, etc.)
116-
- [ ] Redirect container logs to files
117-
- [ ] Add .env variable for log level
118-
119-
### Translate
120-
- [ ] Make translation
121-
122-
### Styling
123-
- [ ] Make the layout responsive
124-
- [x] Improve article detail view
125-
- [ ] Add article parameters to the article list page
126-
- [x] Update Eskoz Theme
127-
128-
### Deployment
129-
- [x] Add an automatic script to load SSL certificates and simplify deployment
130-
131-
### Authentication / Users
132-
- [ ] Finish connection with 2FA OTP
133-
134-
### Views / Pages
135-
- [x] View Page Settings (block view if false)
136-
- [ ] Add members page
137-
138-
### New Apps
139-
- [X] Create Course app
140123

141124
## Key Features
142125
- Ready-to-use multilingual blog
143126
- Easy deployment with Docker
144127
- Built-in Django admin interface
145128

146129

130+
## Contributing
131+
Contributions are welcome! Eskoz uses [Conventional Commits](https://www.conventionalcommits.org/)
132+
for automated versioning and releases (via release-please), with quality and tests
133+
enforced in CI. See [CONTRIBUTING.md](CONTRIBUTING.md) for the commit convention,
134+
local setup, and the full release workflow.
135+
147136
## License
148137
This project is licensed under the GNU General Public License v3.0.
149138
See the [LICENSE](LICENSE) file for more details.

‎docs/customization/themes.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Themes
2+
3+
Eskoz separates presentation from the core through a theming system. Themes live
4+
in the `themes/` directory; the active one is selected with the `THEME`
5+
environment variable (default: `Eskoz`).
6+
7+
## List available themes
8+
9+
```sh
10+
python3 manage.py list_themes
11+
```
12+
13+
Example output:
14+
15+
```text
16+
Name Path Active
17+
---------------------------------------------------------------------------------------------
18+
Eskoz /Eskoz/themes/Eskoz Yes
19+
20+
Successfully listed 1 theme(s).
21+
```
22+
23+
## Create a new theme
24+
25+
From the default structure:
26+
27+
```sh
28+
python3 manage.py create_theme MyNewTheme
29+
```
30+
31+
This generates the necessary folders and files under `themes/`.
32+
33+
Based on an existing theme (e.g. `Eskoz`):
34+
35+
```sh
36+
python3 manage.py create_theme MyNewTheme Eskoz
37+
```
38+
39+
This copies all templates and static files from the base theme.
40+
41+
Once created, customize:
42+
43+
- HTML templates in `templates/`
44+
- Styles and scripts in `static/`
45+
46+
See the [Django Template Language documentation](https://docs.djangoproject.com/en/5.2/ref/templates/language/)
47+
for template syntax.
48+
49+
## Apply a theme
50+
51+
Set it in `.env`:
52+
53+
```ini
54+
THEME=MyNewTheme
55+
```
56+
57+
Then restart the app so the change takes effect:
58+
59+
=== "Docker"
60+
```sh
61+
docker compose -f docker/docker-compose.yml up --build -d
62+
```
63+
64+
=== "Bare metal"
65+
```sh
66+
sudo systemctl restart eskoz
67+
```
68+
69+
Your new theme should now be visible on the site.

0 commit comments

Comments
 (0)