160 lines
4.4 KiB
Markdown
160 lines
4.4 KiB
Markdown
<p align="center">
|
|
<a href="https://stephan.hadan.de">
|
|
<img src="https://git.hadan-it.com/web/stephan.hadan.de/raw/branch/main/docs/assets/logo.png" width="192" alt="Stephan Hadan">
|
|
</a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<strong>
|
|
Stephan Hadan's
|
|
<a href="https://stephan.hadan.de/">private Website</a>
|
|
</strong>
|
|
</p>
|
|
|
|
<!-- BADGIE TIME -->
|
|
|
|
|
|
|
|
<!-- END BADGIE TIME -->
|
|
|
|
<p align="center">
|
|
<a href="https://git.hadan-it.com/web/stephan.hadan.de/actions"><img
|
|
src="https://git.hadan-it.com/web/stephan.hadan.de/actions/workflows/ci.yml/badge.svg?branch=main"
|
|
alt="Build"
|
|
/></a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://squidfunk.github.io/mkdocs-material/"><img
|
|
src="https://shields.hadan-it.com/badge/Material_for_MkDocs-526CFE?style=for-the-badge&logo=MaterialForMkDocs&logoColor=white"
|
|
alt="Built with Material for MkDocs"
|
|
/></a>
|
|
</p>
|
|
|
|
## Sites
|
|
|
|
| **Environment** | **URL** |
|
|
|-----------------|-----------------------------------------|
|
|
| Staging | https://stephan.preview.hadan.de |
|
|
| Production | https://stephan.hadan.de |
|
|
|
|
## Participate
|
|
|
|
1. Make sure you are already have an account at https://git.hadan-it.com. If not pls be so kind to contact support@hadan-it.com.
|
|
2. Contact support@hadan-it.com to be granted access to the stephan.hadan.de-repository.
|
|
|
|
## Development
|
|
|
|
Checkout this project:
|
|
|
|
```
|
|
git clone ssh://git@git.hadan-it.com:222/web/stephan.hadan.de.git
|
|
```
|
|
|
|
Install Python 3.12 with brew:
|
|
|
|
```
|
|
brew install python@3.12
|
|
```
|
|
|
|
Create a virtual environment at the project root - this is used to isolate project packages from the global packages.
|
|
|
|
```
|
|
$ python3.12 -m venv venv
|
|
```
|
|
|
|
Activate the environment.
|
|
|
|
```
|
|
$ source venv/bin/activate
|
|
```
|
|
|
|
Install mkdocs - this is covered in the project requirements file. Make sure you are at projects root.
|
|
|
|
```
|
|
$ make install
|
|
```
|
|
|
|
From time to time it is necessary to run the last command to update your mkdocs environment. Just run `make install` at regular intervals to stay up-to-date.
|
|
|
|
### Upgrade to Python 3.12
|
|
|
|
Delete your venv folder inside your already existing checked out repository:
|
|
|
|
```
|
|
rm -rf venv
|
|
```
|
|
|
|
After that, close your terminal session, create a new one, navigate to your repository again. Then: please continue with "Install Python 3.12 with brew" in the above paragraph and update your environment
|
|
|
|
### Folder structure
|
|
|
|
```
|
|
.
|
|
├── CHANGELOG
|
|
├── LICENSE
|
|
├── README.md
|
|
├── docs
|
|
├── macros
|
|
│ └── __init__.py
|
|
├── mkdocs.yml
|
|
├── overrides
|
|
├── renovate.json
|
|
├── requirements.txt
|
|
├── resources
|
|
└── venv
|
|
```
|
|
|
|
### Install dependencies for optimization function
|
|
|
|
#### macOS
|
|
|
|
```
|
|
$ brew install cairo freetype libffi libjpeg libpng zlib pngquant
|
|
```
|
|
|
|
#### Linux
|
|
|
|
```
|
|
$ apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev pngquant
|
|
```
|
|
|
|
### Install WeasyPrint dependencies
|
|
|
|
#### macOS
|
|
|
|
The easiest way to install WeasyPrint on macOS is to use Homebrew.
|
|
|
|
When Homebrew is installed, install Python, Pango and libffi:
|
|
|
|
```
|
|
$ brew install python pango libffi rust jpeg
|
|
```
|
|
|
|
### Generate and preview full documentation locally
|
|
|
|
In the root of the checked out repository just use the following command to serve the documentation:
|
|
|
|
```
|
|
$ mkdocs serve
|
|
```
|
|
|
|
This will spin up your instance on port 8000 reacting on any changes you make until you stop the service with Ctrl+C
|
|
|
|
## Contribute code/documentation
|
|
|
|
To ensure a reasonable joint development of the documentation, it is necessary to derive each change reasonably into a separately named branch. The following prefixes are available for this purpose:
|
|
|
|
* feat/ for new features/documentation
|
|
* hotfix/ for changes to existing documentation
|
|
|
|
Examples:
|
|
|
|
* feat/new-blog-post
|
|
* hotfix/translation-of-blog-entry
|
|
|
|
After the development of the branch has been completed and extensively tested locally, a corresponding merge request is created in the **develop** branch and approved by a colleague. This ensures a high quality of the documentation and the necessary review.
|
|
|
|
Once the request has been approved, it can be merged into the develop branch. An automatic build pipeline builds the new devel status on https://stephan.preview.hadan.de for reasons of overview, the source branch should be deleted accordingly during the merge.
|
|
|
|
A merge from Devel to Main and a deployment via a build pipeline to https://stephan.hadan.de takes place at regular intervals. This merge is only carried out after consultation.
|