uEdition 0.7.0__tar.gz → 0.8.0__tar.gz

{uedition-0.7.0 → uedition-0.8.0}/.github/workflows/codestyle.yml

@@ -11,6 +11,6 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     - uses: psf/black@stable

{uedition-0.7.0 → uedition-0.8.0}/.github/workflows/coverage.yml

@@ -9,9 +9,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: |
           3.10
@@ -40,7 +40,7 @@ jobs:
         echo "### Total coverage: ${TOTAL}%" >> $GITHUB_STEP_SUMMARY
 
     - name: "Make badge"
-      uses: schneegans/dynamic-badges-action@v1.6.0
+      uses: schneegans/dynamic-badges-action@v1.7.0
       with:
         auth: ${{ secrets.GIST_TOKEN }}
         gistID: 13b76c3c8e59fa624d03918fafde3f2d

uedition-0.8.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/uedition
+
+    permissions:
+      id-token: write
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: |
+          3.11
+
+    - name: Install Base Dependencies
+      run: |
+        sudo apt-get install python3-venv
+        sudo pip install hatch
+
+    - name: Build the package
+      run: |
+        hatch build
+
+    - name: Publish package distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

{uedition-0.7.0 → uedition-0.8.0}/.github/workflows/tests.yml

@@ -11,9 +11,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
-    - uses: actions/setup-python@v4
+    - uses: actions/setup-python@v5
       with:
         python-version: |
           3.10

uedition-0.8.0/.readthedocs.yml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  commands:
+    - "pip install hatch"
+    - "cd docs && hatch run build"
+    - "mkdir $READTHEDOCS_OUTPUT"
+    - "mv docs/site $READTHEDOCS_OUTPUT/html"
+
+python:
+  install:
+    - method: pip
+      path: .

uedition-0.8.0/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python.analysis.typeCheckingMode": "basic"
+}

{uedition-0.7.0 → uedition-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: uEdition
-Version: 0.7.0
+Version: 0.8.0
 Project-URL: Documentation, https://github.com/unknown/uedition#readme
 Project-URL: Issues, https://github.com/unknown/uedition/issues
 Project-URL: Source, https://github.com/unknown/uedition
@@ -14,11 +14,12 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.10
-Requires-Dist: copier<9.0.0,>=8.0.0
+Requires-Dist: copier<10.0.0,>=9.0.0
 Requires-Dist: jupyter-book<1.0.0,>=0.15.1
 Requires-Dist: livereload
-Requires-Dist: lxml<5.0.0,>=4.9.2
-Requires-Dist: pydantic[dotenv]<2.0.0,>=1.0.0
+Requires-Dist: lxml<6.0.0,>=4.9.2
+Requires-Dist: pydantic-settings<3.0.0,>=2.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
 Requires-Dist: pyyaml<7.0.0,>=6.0.0
 Requires-Dist: typer[all]<1.0.0
 Description-Content-Type: text/markdown

uedition-0.8.0/docs/.gitignore

@@ -0,0 +1,5 @@
+_build
+site
+_toc.yml
+_config.yml
+_static

uedition-0.8.0/docs/.uEdition.answers

@@ -0,0 +1,9 @@
+# Changes here will be overwritten by Copier
+_commit: v0.0.11-2-gf9997e6
+_src_path: ../uEdition-project-template/
+author_email: mark.hall@work.room3b.eu
+author_name: Mark Hall
+edition_name: μEdition
+publishing: ''
+repository_branch: main
+repository_url: https://github.com/uEdition/uEdition

uedition-0.8.0/docs/de/.uEdition.answers

@@ -0,0 +1,5 @@
+# Changes here will be overwritten by Copier
+_commit: v0.0.2
+_src_path: gh:uEdition/uEdition-language-template
+code: de
+label: Deutsch

uedition-0.8.0/docs/de/index.md

@@ -0,0 +1,55 @@
+# μEdition
+
+Das Erstellen einer kritischen, digitalen Edition bringt mit sich eine Reihe signifikanter Hürden, besonders wenn es um
+die technischen Anforderungen und Hostingkosten geht. Die μEdition bietet ein Gerüst um diese Hürden zu reduzieren, indem
+es ein einfaches Werkzeug anbietet, welches Projekte darin unterstützt einfach (multilinguale) digitale Editionen zu
+erstellen, welche dann über gratis oder billige Hostinglösungen online verfügbar gemacht werden können.
+
+## Inhaltsverzeichnis
+
+:::{tableofcontents}
+:::
+
+## Schnellstart
+
+Für einen Schnellstart mit der μEdition, folgens sie diesen Schritten (Python 3.10 oder nuer muss bereits installiert sein):
+
+:::{code} console
+$ pipx install hatch copier
+$ copier copy https://github.com/uEdition/uEdition-project-template my-edition
+🎤 What is the name of your μEdition?
+   My Edition
+🎤 What is the μEdition author's name?
+   A.N. Editor
+🎤 What is the μEdition author's address?
+   a.n.editor@example.com
+🎤 Do you wish to automatically publish your μEdition?
+   (Use arrow keys)
+ » Disable automatic publishing
+   Via GitHub Pages
+   Via Read the Docs
+🎤 What is the URL of the repository containing your μEdition?
+   https://github.com/aneditor/my-edition
+🎤 What is the repository branch containing your μEdition?
+   main
+
+Copying from template version 0.0.10
+    create  .
+    create  toc.yml
+    create  uEdition.yml
+    create  .uEdition.answers
+    create  .github
+    create  .github/workflows
+    create  .github/workflows/pages.yml
+    create  .gitignore
+    create  pyproject.toml
+$ cd my-edition
+$ hatch run uEdition language add cy
+🎤 What is the language code?
+   cy
+🎤 What is the name of the language?
+   Cymraeg
+$ hatch run serve
+:::
+
+Die neue, digitale Edition ist dann unter http://localhost:8000 verfügbar.

uedition-0.8.0/docs/de/user/configuration.md

@@ -0,0 +1,29 @@
+# Configuring the μEdition
+
+The μEdition and Jupyter Book are highly configurable and in the μEdition both are configured via the {file}`uEdition.yml`
+file in the μEdition root. The block below shows the available configuration options that can be used in that file:
+
+:::{code-block} yaml
+author:           # The author information consisting of:
+  name:           #   The name to display
+  email:          #   The e-mail address to use
+jb_config:        # Can contain any valid Jupyter Book configuration settings
+languages:        # The languages configured for the μEdition. A list, where each item consists of:
+- code:           #   The ISO 639-1 two-letter language code
+  label:          #   The label to display for this language
+  path:           #   The path that contains the language-specific Jupyter Book
+output:           # The output directory for the complete μEdition
+repository:       # The repository that contains this μEdition, configured via:
+  url:            #   The URL to the repository
+  branch:         #   The branch containing the μEdition
+title:            # The title of the μEdition in all configured languages. Each configured language code must have a key in this mapping:
+  en:             #   Mapping from ISO 639-1 language code to the human-readable title
+version: '1'      # The version of the μEdition configuration, which must be set to "1"
+:::
+
+All elements of this file are optional and working defaults will be substituted.
+
+All elements of the Jupyter Book can be configured via the `jb_config` settings ([see here for a full list](https://jupyterbook.org/en/stable/customize/config.html)).
+These values will be used as they are for all configured language-specific Jupyter Books. The only exception to this is
+the `title` configuration setting, for which the μEdition will always use the language-specific value configured in the
+{file}`uEdition.yml`.

uedition-0.8.0/docs/de/user/content.md

@@ -0,0 +1,55 @@
+# Writing Content
+
+The μEdition uses [Jupyter Book](https://jupyterbook.org) as its underlying technology for turning your text into a
+publishable website. Each language in the μEdition is a separate Jupyter Book and the μEdition provides the glue that
+merges the individual outputs together into a single site. This is achieved by moving the Jupyter Book configuration
+into shared configuration files. When the μEdition builds the final website, language-specific versions of the
+configurations are added to each language-specific Jupyter Book, before the Jupyter Book build process is then run
+for each language. Due to this structure, most of the guidance that the Jupyter Book project provides for writing
+and configuring Jupyter Book projects can be used in the μEdition.
+
+## Structuring the μEdition
+
+The structure of the μEdition is defined via its table of contents, which is configured in the {file}`toc.yml` file
+in the μEdition root folder. The {file}`toc.yml` file uses the same format as [defined by the Jupyter Book project](https://jupyterbook.org/en/stable/structure/toc.html).
+The only difference is that where the standard Jupyter Book table of contents has a single `title` or `caption`,
+in the μEdition these entries can contain a mapping of language code to text. When generating the language-specific
+table of contents the μEdition ensures that the correct language value is used for the caption or title for that
+language:
+
+:::{code-block} yaml
+format: jb-book
+root: index
+parts:
+  - caption:
+      en: Name of Part 1
+      de: Name von Teil 1
+    chapters:
+    - title:
+        en: Chapter 1
+        de: Chapter 2
+      file: path/to/part1/chapter1
+    - file: path/to/part1/chapter2
+:::
+
+## Writing text content
+
+Jupter Book primarily uses MyST or Markedly Structured Text for writing text content, which is an extension of Markdown
+designed for publishable content. A good overview over the core functionality can be found
+[here](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html). Jupyter Book provides a range of extensions
+built upon the core MySQ structure, which are documented [here](https://jupyterbook.org/en/stable/content/index.html)
+and which include useful things like glossaries, indices, citations, footnotes, plus elements for structuring the layout
+of the page and its content.
+
+## Local server
+
+While writing it can be helpful to see what the result will look like. To simplify this, the μEdition provides a built-in
+web-server that automatically re-generates the website when you edit the content. To start this server, run the
+following command:
+
+:::{code-block} console
+$ hatch run serve
+:::
+
+This will build the μEdition and then make it available at http://localhost:8000. When you make changes to the content,
+the μEdition will automatically re-build the website and automatically reload the view in the browser.

uedition-0.8.0/docs/de/user/create.md

@@ -0,0 +1,13 @@
+# Creating a μEdition
+
+With all the pre-requisites installed correctly, you are now ready to create your first μEdition. On the commandline
+navigate to the folder where you want to create your μEdition and run:
+
+:::{code-block} console
+$ copier copy https://github.com/uEdition/uEdition-project-template my-edition
+:::
+
+Replace `my-edition` with the name of the folder you want your edition to be created in. The setup process will ask
+you a few questions about your new μEdition and create a skeleton μEdition in the folder you specified.
+
+On the commandline, navigate into that new folder and all further commands are to be run inside that folder.

uedition-0.8.0/docs/de/user/index.md

@@ -0,0 +1,7 @@
+# User Guide
+
+Welcome to the μEdition User Guide, which guides you, the editor, through the process of {doc}`creating a new μEdition <create>`,
+{doc}`adding languages <language-add>` and {doc}`content <content>` to it, and {doc}`publishing it to GitHub Pages <publish>`.
+
+The user guide tries to assume as little prior knowledge as possible, but you are expected to be able to navigate the
+command-line. Additionally, for publishing via GitHub Pages, basic Git knowledge is also required.

uedition-0.8.0/docs/de/user/installation.md

@@ -0,0 +1,37 @@
+# Installation
+
+The μEdition is built on top of a set of other tools and in order to create our first μEdition, it is necessary to first
+install these dependencies.
+
+The μEdition is built in Python and supports version 3.10 and 3.11 [^python-version]. In order to use it, please
+[install an appropriate version of Python for your operating system](https://python.org/downloads).
+
+For the initial creation of a new μEdition, the μEdition uses a tool called [Copier](https://copier.readthedocs.io/en/stable/).
+To install all required μEdition dependencies and to run the various μEdition tools, [Hatch](https://hatch.pypa.io)
+is used.
+
+The easiest way to install both Copier and Hatch is via [pipx](https://pypa.github.io/pipx/), which you can
+[install from here](https://pypa.github.io/pipx/installation/). When you have pipx installed, then on the commandline
+run the following command to install Copier:
+
+:::{code} console
+$ pipx install copier
+$ pipx install hatch
+:::
+
+You can test that your installation has been successful by running
+
+:::{code} console
+$ copier
+$ hatch
+:::
+
+If the two commands show you a summary of the available options and commands, then the core tools are installed correctly.
+
+In order to work collaboratively and for the GitHub Pages publishing functionality to work, you also need to install the
+version control system [Git](https://git-scm.com/downloads). Providing you with a full intro to using git exceeds the
+space we have here, but there are many good git tutorials out there and there is also the
+[official documentation](https://git-scm.com/doc).
+
+[^python-version]: The μEdition is tested using Python 3.10 and 3.11. It may also work on newer Python version,
+  it just hasn't been tested on those.

uedition-0.8.0/docs/de/user/language-add.md

@@ -0,0 +1,14 @@
+# Adding a Language
+
+The μEdition has multi-language support as a core principle. Thus, even if you are planning to release your edition in
+a single language only, you need to explicitly configure this one language.
+
+To add a language to your μEdition, run the following command:
+
+:::{code-block} console
+$ hatch run uEdition language add FOLDER_NAME
+:::
+
+Replace `FOLDER_NAME` with the name of the folder that the μEdition content for that language is to be placed in. The
+process will ask you for some detail about the language you are adding and will then create skeleton in the folder,
+which is then ready for editing.

uedition-0.8.0/docs/de/user/language-update.md

@@ -0,0 +1,12 @@
+# Updating a Language
+
+The μEdition uses the same template approach for each language that you set up and these need to be updated separately
+from the main update. Run the following command to update a single language:
+
+:::{code-block} console
+$ hatch run uEdition language update PATH
+:::
+
+Replace `PATH` with the name of the folder of the language you wish to update.
+
+As with updating the main μEdition, check all files, before continuing with your work.

uedition-0.8.0/docs/de/user/publish.md

@@ -0,0 +1,33 @@
+# Publishing the μEdition
+
+When you have your μEdition in a state that you want to publish it, then run the following command to generate the
+publishable version:
+
+:::{code-block} console
+$ hatch run publish
+:::
+
+The μEdition will build the site into the configured output folder, which by default is {file}`site`. You can then
+copy the content of this folder to your chosen hosting solution.
+
+## Publishing to GitHub Pages
+
+The μEdition comes with built-in support for publishing your μEdition via [GitHub Pages](https://pages.github.com/).
+To do this, you need to have
+
+* The μEdition set up to use git.
+* An account on [GitHub](https://www.github.com).
+* A repository set up on GitHub and the μEdition pushed to that repository
+
+Then on GitHub in your repository navigate to {guilabel}`Settings` and then {guilabel}`Pages`. On the {guilabel}`Pages`
+page ensure that under the {guilabel}`Build and deployment` heading, the {guilabel}`Source` dropdown is set to
+"GitHub Actions".
+
+To run the build manually, on GitHub navigate to {guilabel}`Actions` in your repository and then select the
+{guilabel}`Publish the site` workflow on the left. This workflow can be triggered manually. Click on the
+{guilabel}`Run workflow` button and then on the green {guilabel}`Run workflow` button in the popup. This will start
+the build and deployment process and when the workflow is completed, you can access your μEdition at the URL that
+is shown at the top of the {guilabel}`Settings` > {guilabel}`Pages` page.
+
+The workflow is also set to automatically rebuild and deploy the μEdition whenever you push a change to the main
+branch.

uedition-0.8.0/docs/de/user/update.md

@@ -0,0 +1,13 @@
+# Updating the μEdition
+
+The μEdition template is updated from time to time. In order to ensure that your μEdition is up-to-date with the latest
+release, simply run
+
+:::{code-block} console
+$ hatch run update
+:::
+
+This will apply all the changes that were made to the template since you created the μEdition or since you last performed
+an update.
+
+It is recommended that you check the files that the update marks as "changed", before moving on with your work.

uedition-0.8.0/docs/en/.uEdition.answers

@@ -0,0 +1,5 @@
+# Changes here will be overwritten by Copier
+_commit: v0.0.2
+_src_path: gh:uEdition/uEdition-language-template
+code: en
+label: English

uedition-0.8.0/docs/en/index.md

@@ -0,0 +1,55 @@
+# μEdition
+
+The process of creating and making available a (critical) digital edition often presents projects with a range of significant
+hurdles, particularly around technical knowledge and hosting costs. The μEdition is a framwork that lowers these barriers by
+providing a simple tool that supports users in easily building (multi-lingual) digital editions that can then easily be made
+available online using free or low-cost hosting solutions.
+
+## Contents
+
+:::{tableofcontents}
+:::
+
+## Quickstart
+
+To quickly get started with the μEdition, follow these steps (assuming you already have Python 3.10 or newer installed):
+
+:::{code} console
+$ pipx install hatch copier
+$ copier copy https://github.com/uEdition/uEdition-project-template my-edition
+🎤 What is the name of your μEdition?
+   My Edition
+🎤 What is the μEdition author's name?
+   A.N. Editor
+🎤 What is the μEdition author's address?
+   a.n.editor@example.com
+🎤 Do you wish to automatically publish your μEdition?
+   (Use arrow keys)
+ » Disable automatic publishing
+   Via GitHub Pages
+   Via Read the Docs
+🎤 What is the URL of the repository containing your μEdition?
+   https://github.com/aneditor/my-edition
+🎤 What is the repository branch containing your μEdition?
+   main
+
+Copying from template version 0.0.10
+    create  .
+    create  toc.yml
+    create  uEdition.yml
+    create  .uEdition.answers
+    create  .github
+    create  .github/workflows
+    create  .github/workflows/pages.yml
+    create  .gitignore
+    create  pyproject.toml
+$ cd my-edition
+$ hatch run uEdition language add cy
+🎤 What is the language code?
+   cy
+🎤 What is the name of the language?
+   Cymraeg
+$ hatch run serve
+:::
+
+Your new digital edition will be available at http://localhost:8000.

uedition-0.8.0/docs/en/user/configuration.md

@@ -0,0 +1,29 @@
+# Configuring the μEdition
+
+The μEdition and Jupyter Book are highly configurable and in the μEdition both are configured via the {file}`uEdition.yml`
+file in the μEdition root. The block below shows the available configuration options that can be used in that file:
+
+:::{code-block} yaml
+author:           # The author information consisting of:
+  name:           #   The name to display
+  email:          #   The e-mail address to use
+jb_config:        # Can contain any valid Jupyter Book configuration settings
+languages:        # The languages configured for the μEdition. A list, where each item consists of:
+- code:           #   The ISO 639-1 two-letter language code
+  label:          #   The label to display for this language
+  path:           #   The path that contains the language-specific Jupyter Book
+output:           # The output directory for the complete μEdition
+repository:       # The repository that contains this μEdition, configured via:
+  url:            #   The URL to the repository
+  branch:         #   The branch containing the μEdition
+title:            # The title of the μEdition in all configured languages. Each configured language code must have a key in this mapping:
+  en:             #   Mapping from ISO 639-1 language code to the human-readable title
+version: '1'      # The version of the μEdition configuration, which must be set to "1"
+:::
+
+All elements of this file are optional and working defaults will be substituted.
+
+All elements of the Jupyter Book can be configured via the `jb_config` settings ([see here for a full list](https://jupyterbook.org/en/stable/customize/config.html)).
+These values will be used as they are for all configured language-specific Jupyter Books. The only exception to this is
+the `title` configuration setting, for which the μEdition will always use the language-specific value configured in the
+{file}`uEdition.yml`.

uedition-0.8.0/docs/en/user/content.md

@@ -0,0 +1,55 @@
+# Writing Content
+
+The μEdition uses [Jupyter Book](https://jupyterbook.org) as its underlying technology for turning your text into a
+publishable website. Each language in the μEdition is a separate Jupyter Book and the μEdition provides the glue that
+merges the individual outputs together into a single site. This is achieved by moving the Jupyter Book configuration
+into shared configuration files. When the μEdition builds the final website, language-specific versions of the
+configurations are added to each language-specific Jupyter Book, before the Jupyter Book build process is then run
+for each language. Due to this structure, most of the guidance that the Jupyter Book project provides for writing
+and configuring Jupyter Book projects can be used in the μEdition.
+
+## Structuring the μEdition
+
+The structure of the μEdition is defined via its table of contents, which is configured in the {file}`toc.yml` file
+in the μEdition root folder. The {file}`toc.yml` file uses the same format as [defined by the Jupyter Book project](https://jupyterbook.org/en/stable/structure/toc.html).
+The only difference is that where the standard Jupyter Book table of contents has a single `title` or `caption`,
+in the μEdition these entries can contain a mapping of language code to text. When generating the language-specific
+table of contents the μEdition ensures that the correct language value is used for the caption or title for that
+language:
+
+:::{code-block} yaml
+format: jb-book
+root: index
+parts:
+  - caption:
+      en: Name of Part 1
+      de: Name von Teil 1
+    chapters:
+    - title:
+        en: Chapter 1
+        de: Chapter 2
+      file: path/to/part1/chapter1
+    - file: path/to/part1/chapter2
+:::
+
+## Writing text content
+
+Jupter Book primarily uses MyST or Markedly Structured Text for writing text content, which is an extension of Markdown
+designed for publishable content. A good overview over the core functionality can be found
+[here](https://myst-parser.readthedocs.io/en/latest/syntax/typography.html). Jupyter Book provides a range of extensions
+built upon the core MySQ structure, which are documented [here](https://jupyterbook.org/en/stable/content/index.html)
+and which include useful things like glossaries, indices, citations, footnotes, plus elements for structuring the layout
+of the page and its content.
+
+## Local server
+
+While writing it can be helpful to see what the result will look like. To simplify this, the μEdition provides a built-in
+web-server that automatically re-generates the website when you edit the content. To start this server, run the
+following command:
+
+:::{code-block} console
+$ hatch run serve
+:::
+
+This will build the μEdition and then make it available at http://localhost:8000. When you make changes to the content,
+the μEdition will automatically re-build the website and automatically reload the view in the browser.

uedition-0.8.0/docs/en/user/create.md

@@ -0,0 +1,13 @@
+# Creating a μEdition
+
+With all the pre-requisites installed correctly, you are now ready to create your first μEdition. On the commandline
+navigate to the folder where you want to create your μEdition and run:
+
+:::{code-block} console
+$ copier copy https://github.com/uEdition/uEdition-project-template my-edition
+:::
+
+Replace `my-edition` with the name of the folder you want your edition to be created in. The setup process will ask
+you a few questions about your new μEdition and create a skeleton μEdition in the folder you specified.
+
+On the commandline, navigate into that new folder and all further commands are to be run inside that folder.

uedition-0.8.0/docs/en/user/index.md

@@ -0,0 +1,7 @@
+# User Guide
+
+Welcome to the μEdition User Guide, which guides you, the editor, through the process of {doc}`creating a new μEdition <create>`,
+{doc}`adding languages <language-add>` and {doc}`content <content>` to it, and {doc}`publishing it to GitHub Pages <publish>`.
+
+The user guide tries to assume as little prior knowledge as possible, but you are expected to be able to navigate the
+command-line. Additionally, for publishing via GitHub Pages, basic Git knowledge is also required.

uedition-0.8.0/docs/en/user/installation.md

@@ -0,0 +1,37 @@
+# Installation
+
+The μEdition is built on top of a set of other tools and in order to create our first μEdition, it is necessary to first
+install these dependencies.
+
+The μEdition is built in Python and supports version 3.10 and 3.11 [^python-version]. In order to use it, please
+[install an appropriate version of Python for your operating system](https://python.org/downloads).
+
+For the initial creation of a new μEdition, the μEdition uses a tool called [Copier](https://copier.readthedocs.io/en/stable/).
+To install all required μEdition dependencies and to run the various μEdition tools, [Hatch](https://hatch.pypa.io)
+is used.
+
+The easiest way to install both Copier and Hatch is via [pipx](https://pypa.github.io/pipx/), which you can
+[install from here](https://pypa.github.io/pipx/installation/). When you have pipx installed, then on the commandline
+run the following command to install Copier:
+
+:::{code} console
+$ pipx install copier
+$ pipx install hatch
+:::
+
+You can test that your installation has been successful by running
+
+:::{code} console
+$ copier
+$ hatch
+:::
+
+If the two commands show you a summary of the available options and commands, then the core tools are installed correctly.
+
+In order to work collaboratively and for the GitHub Pages publishing functionality to work, you also need to install the
+version control system [Git](https://git-scm.com/downloads). Providing you with a full intro to using git exceeds the
+space we have here, but there are many good git tutorials out there and there is also the
+[official documentation](https://git-scm.com/doc).
+
+[^python-version]: The μEdition is tested using Python 3.10 and 3.11. It may also work on newer Python version,
+  it just hasn't been tested on those.