Skip to content

Commit

Permalink
Merge pull request #212 from SSRQ-SDS-FDS/dev
Browse files Browse the repository at this point in the history
1.0.0 release PR
  • Loading branch information
Bpolitycki committed Sep 27, 2023
2 parents 1c9f2df + 78d1165 commit bb03c6e
Show file tree
Hide file tree
Showing 557 changed files with 13,078 additions and 12,149 deletions.
49 changes: 49 additions & 0 deletions .github/actions/mike/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
name: Deploy using mike
description: A action which deploys an mkdocs site using mike.

inputs:
version-name:
description: The name of the version as well as the name of the target folder
required: true

runs:
using: composite
steps:
- name: Configure Git user
shell: bash
run: |
git config --local user.email "github-actions[bot]@users.noreply.github.com"
git config --local user.name "github-actions[bot]"
- name: Deploy dev
if: ${{ inputs.version-name == 'dev' }}
run: |
if poetry run mike list | grep -q "dev"; then
dev_exists=true
else
dev_exists=false
fi
if $dev_exists; then
poetry run mike delete dev --push
fi
poetry run mike deploy dev --push
if poetry run mike list | grep -q "latest"; then
latest_exists=true
else
latest_exists=false
fi
if ! $latest_exists; then
poetry run mike set-default dev --push
fi
shell: bash
- name: Deploy concrete docs version
if: ${{ inputs.version-name == 'main' }}
run: |
VERSION_NUMBER=$(grep -oE '"SLS TEI-Schema".*\sversion\s?=\s?"([0-9a-zA-Z.-]+)"' pyproject.toml | sed -n 's/.*version = "\(.*\)".*/\1/p')
poetry run mike deploy ${VERSION_NUMBER} latest --update-aliases --no-redirect --push
poetry run mike set-default latest --push
shell: bash
34 changes: 34 additions & 0 deletions .github/actions/setup/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
name: Setup SSH, Python and Poetry
description: A simple action to setup everything, including dependencies.

inputs:
poetry-version:
description: Poetry version
required: false
default: '1.2.2'
python-version:
description: Python version
required: false
default: '3.11'
ssh-key:
description: The ssh-key
required: true

runs:
using: composite
steps:
- name: Setup access to private repo(s)
uses: webfactory/[email protected]
with:
ssh-private-key: ${{ inputs.ssh-key }}
- name: Install poetry
shell: bash
run: pipx install poetry==${{ inputs.poetry-version }}
- name: Set up Python 3.11
uses: actions/setup-python@v4
with:
cache: 'poetry'
python-version: ${{ inputs.python-version }}
- name: Install dependencies
shell: bash
run: poetry install
63 changes: 40 additions & 23 deletions .github/workflows/pr_to_dev.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,47 +3,64 @@ name: test_and_publish_dev
on:
pull_request:
branches: ['dev']
push:
branches: ['dev']
workflow_dispatch:

permissions:
contents: read
concurrency:
group: 'pages'
cancel-in-progress: false

jobs:
ci:
strategy:
fail-fast: false
matrix:
python-version: ['3.11']
poetry-version: ['1.2.2']

test:
runs-on: ubuntu-latest

steps:
- name: Checkout repo
uses: actions/checkout@v3
with:
submodules: 'recursive'
- name: Setup access to private repo(s)
uses: webfactory/[email protected]
with:
ssh-private-key: ${{ secrets.CLI_SECRET_KEY }}
- name: Set up Python 3.11
uses: actions/setup-python@v4
- name: Setup SSH and Python with Poetry
uses: ./.github/actions/setup
with:
python-version: ${{ matrix.python-version }}
- name: Setup Poetry
uses: abatilo/actions-poetry@v2
with:
poetry-version: ${{ matrix.poetry-version }}
ssh-key: ${{ secrets.CLI_SECRET_KEY }}
- name: Setup xmllint
uses: Bpolitycki/[email protected]
- name: Install dependencies
run: poetry install
- name: Check the formatting of .py-files
run: ./Taskfile fmt-check
- name: Check the formatting of .xml-files
run: ./Taskfile fmt-xml
- name: Lint all .py-files
run: ./Taskfile lint-only
- name: Validate all schema source files
run: ./Taskfile validate
- name: Run all tests using pytest
run: poetry run pytest -n 4

publish:
runs-on: ubuntu-latest
if: github.event_name != 'pull_request'
needs: test
permissions:
contents: write
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PRE_COMMIT_ALLOW_NO_CONFIG: 1

steps:
- name: Checkout repo
uses: actions/checkout@v3
with:
submodules: 'recursive'
fetch-depth: 0
- name: Setup SSH and Python with Poetry
uses: ./.github/actions/setup
with:
ssh-key: ${{ secrets.CLI_SECRET_KEY }}
- name: Set docs-url
run: |
url=$(gh api "repos/$GITHUB_REPOSITORY/pages" --jq '.html_url')
echo "DOCS_URL=${url}" >> "$GITHUB_ENV"
- name: Build and publish
uses: ./.github/actions/mike
with:
version-name: 'dev'
33 changes: 32 additions & 1 deletion .github/workflows/pr_to_main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,23 @@ name: test_and_release
on:
pull_request:
branches: ['main']
push:
branches: ['main']
workflow_dispatch:

permissions:
contents: read

jobs:
ci:
test:
strategy:
fail-fast: false
matrix:
python-version: ['3.11']
poetry-version: ['1.2.2']

runs-on: ubuntu-latest
if: github.event_name == 'pull_request'

steps:
- name: Checkout repo
Expand Down Expand Up @@ -47,3 +50,31 @@ jobs:
run: ./Taskfile lint-only
- name: Run all tests using pytest
run: poetry run pytest -n 4

publish:
runs-on: ubuntu-latest
if: github.event_name != 'pull_request'
permissions:
contents: write
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
PRE_COMMIT_ALLOW_NO_CONFIG: 1

steps:
- name: Checkout repo
uses: actions/checkout@v3
with:
submodules: 'recursive'
fetch-depth: 0
- name: Setup SSH and Python with Poetry
uses: ./.github/actions/setup
with:
ssh-key: ${{ secrets.CLI_SECRET_KEY }}
- name: Set docs-url
run: |
url=$(gh api "repos/$GITHUB_REPOSITORY/pages" --jq '.html_url')
echo "DOCS_URL=${url}" >> "$GITHUB_ENV"
- name: Build and publish
uses: ./.github/actions/mike
with:
version-name: 'main'
4 changes: 3 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,9 @@ venv.bak/
# mkdocs documentation
/site
# ignore docs generated for elements
/docs/elements/*.md
/src/docs/elements/*.md
# Do not ignore the index pages
!/src/docs/elements/index*.md

# mypy
.mypy_cache/
Expand Down
4 changes: 2 additions & 2 deletions .gitmodules
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
[submodule "src/lib/tei_stylesheets"]
path = src/lib/tei_stylesheets
[submodule "utils/schema/lib/tei_stylesheets"]
path = utils/schema/lib/tei_stylesheets
url = https://github.com/TEIC/Stylesheets.git
branch = release-7.54.0
shallow = true
73 changes: 58 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@ Dieses Repository beinhaltet Quellcode und sonstige Dateien im Zusammenhang mit
- [Dokumentation](#dokumentation)
- [Versionierung](#versionierung)
- [Was ist wo?](#was-ist-wo)
- [`doc`](#doc)
- [`src`](#src)
- [`src/docs`](#srcdocs)
- [`src/schema`](#srcschema)
- [Technisches Setup](#technisches-setup)
- [Verwendete Software / Technologien](#verwendete-software--technologien)
- [Einrichtung / Anforderungen an die Umgebung](#einrichtung--anforderungen-an-die-umgebung)
Expand All @@ -17,6 +17,7 @@ Dieses Repository beinhaltet Quellcode und sonstige Dateien im Zusammenhang mit
- [Anpassung von Inhaltstypen](#anpassung-von-inhaltstypen)
- [Anpassung von Attributwerten](#anpassung-von-attributwerten)
- [Anpassung / Erstellung von Tests](#anpassung--erstellung-von-tests)
- [Links zwischen Bestandteilen des Schemas und der (übrigen) Dokuseite](#links-zwischen-bestandteilen-des-schemas-und-der-übrigen-dokuseite)
- [Schema erzeugen](#schema-erzeugen)
- [Erzeugung einer neuen Version und Upload](#erzeugung-einer-neuen-version-und-upload)
- [Erzeugung der Dokumentation](#erzeugung-der-dokumentation)
Expand Down Expand Up @@ -49,22 +50,45 @@ Die Versionsnummer wird als Tag in der Git-History hinterlegt und ist zudem in d

### Was ist wo?

Das Repository besteht aus vier verschiedenen Bereichen:
Das Repository ist wiefolgt aufgeteilt:

1. `doc`: hier befindet sich die Dokumentation, diese wird größtenteils dynamisch aus dem ODD generiert
2. `src`: hier befinden sich die Quelldateien des Schemas
3. `test`: der Name sagt es
4. `dist`: dieser Ordner wird dynamisch generiert und steht nicht unter Versionskontrolle; hier befinden sich die kompilierten Schemadateien
```
ssrq-schema/
├─ .github/
├─ src/
│ ├─ docs/
│ ├─ schema/
│ │ ├─ commons/
│ │ ├─ elements/
│ │ ├─ examples/
│ │ ├─ main.odd.xml
├─ utils/
│ ├─ commons/
│ ├─ docs/
│ ├─ schema/
├─ .gitignore
├─ .gitmodules
├─ CITATION.cff
├─ LICENSE
├─ mkdocs.yml
├─ poetry.lock
├─ pyproject.toml
├─ README.md
├─ Taskfile
```

1. `src`: hier befinden sich die Quelldateien des Schemas sowie Teile der Dokumentation (`.md`), die nicht Teil des ODDs sind
2. `tests`: der Name sagt es
3. `build`: dieser Ordner wird dynamisch generiert und steht nicht unter Versionskontrolle; hier befinden sich die kompilierten Schemadateien sowie die HTML-Doku

#### `doc`
#### `src/docs`

Siehe [Erzeugung der Dokumentation](#erzeugung-der-dokumentation).

#### `src`
#### `src/schema`

- der Unterordner `lib` enthält als git-Submodule die tei-Stylesheets; die verwendete Branch ist in der Datei `.gitmodules` definiert
- der Unterordner `elements` enthält die Schema-Deklarationen je Element; pro spezifizierten Element wird eine Datei nach dem Muster `name.odd.xml` erstellt – sofern verschiedene Spezifikationen für unt. Typen (Einleitung, Transkripte, etc.) festgelegt werden, wird der Typ mit `-type` an den Namen angehängt
- der Unterordner `common` enthält Spezifikationen, die von verschiedenen Teilen des Schemas wiederverwendet werden
- der Unterordner `commons` enthält Spezifikationen, die von verschiedenen Teilen des Schemas wiederverwendet werden
- `classes.odd.xml`: Klassendefinitionen
- `constrains.odd.xml`: globale Schematron-Regeln
- `content.odd.xml`: Inhaltstypen
Expand All @@ -81,6 +105,7 @@ Siehe [Erzeugung der Dokumentation](#erzeugung-der-dokumentation).
- [mkdocs](https://www.mkdocs.org)
- [poetry](https://python-poetry.org)
- [pre-commit](https://pre-commit.com)
- [pydantic](https://pydantic.dev)
- [pytest](https://docs.pytest.org/en/7.1.x/how-to/writing_plugins.html)
- [saxonche](https://pypi.org/project/saxonche/)
- [TEI ODD](https://tei-c.org/guidelines/customization/getting-started-with-p5-odds/)
Expand Down Expand Up @@ -219,9 +244,27 @@ def test_text(
Sollen nur die Tests eines Elements ausgeführt werden, dann kann dazu folgender Befehl verwendet werden:

```sh
run test test/elements/test_cell.py
run test tests/src/schema/elements/test_cell.py
```

#### Links zwischen Bestandteilen des Schemas und der (übrigen) Dokuseite

Aus dem Schema wird statisch eine Dokumentationsseite erzeugt (siehe oben). Einige Bestandteile dieser Seite liegen statisch als `.md`-Dateien vor. Verknüpfungen zwischen Schema und diesen Einzeldateien (oder umgekehrt) können über direkten Verweis auf die jeweilige Datei vorgenommen werden.

Aus dem Schema heraus:

```xml
<ref target="print.md"
````

Oder aus einer Markdown-Datei auf ein Element:

```md
Der Tag [TEI][tei.de.md]
```

Die relative Pfaden (von a zu b) werden während des Build-Prozesses automatisch aufgelöst und müssen **nicht** händisch nachgeführt werden.

### Schema erzeugen

#### Erzeugung einer neuen Version und Upload
Expand All @@ -248,9 +291,9 @@ Die Dokumentation für das Schema zur Validierung der Transkriptionen der ‚St
Die Quelldateien für die Dokumentation sind einerseits die einzelnen Elementdefinitionen, diese befinden sich `/src/elements` und andererseits spezifische Dateien für die Dokuseite:

- `mkdocs.yml`: Konfigurationsdatei für `mkdocs`; enthält ebenso Übersetzungen für die Navigation
- `utils/odd2md.py`: Python-Skript zur Umwandlung der ODD-Datei in einzelne Markdown-Dateien je Element (Quelle ist ein kompiliertes ODD)
- `utils/hook.py`: Hook (‚Event-Skript‘), welches von `mkdocs` beim Start aufgerufen wird – der Hook bindet wiederum `odd2md.py` ein
- `docs`: grundlegende Quelldateien für die Dokuseite
- `utils/docs/odd2md.py`: Python-Skript zur Umwandlung der ODD-Datei in einzelne Markdown-Dateien je Element (Quelle ist ein kompiliertes ODD)
- `utils/docs/doc_hooks.py`: Hook (‚Event-Skript‘), welches von `mkdocs` beim Start aufgerufen wird – der Hook bindet wiederum `odd2md.py` ein
- `src/docs`: grundlegende Quelldateien für die Dokuseite
- `index.md`: Startseite (das Kürzel `.de` oder `.fr` verweist auf die jeweilige Sprachversion)
- `assets`: CSS, Bilddateien usw.
- `base`: Markdowndateien mit statischen Beschreibungstexten (bspw. Datierungsrichtlinien)
Expand Down
4 changes: 2 additions & 2 deletions Taskfile
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ function test-only {

function compile {
validate
cmd python utils/main.py
cmd python utils/schema/compile.py
}

function build-docs {
Expand All @@ -80,7 +80,7 @@ function serve-docs {

function validate {
echo "Checking the xml sources..."
cmd python utils/validate.py
cmd python utils/schema/validate.py
}

function help {
Expand Down
Loading

0 comments on commit bb03c6e

Please sign in to comment.