initial commit

.github/workflows/pages.yml

@@ -0,0 +1,53 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main", ]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+          cache: 'pip' # caching pip dependencies
+      - run: pip install -r requirements.txt
+      - name: Spinx build pages
+        run: |
+            sphinx-build -b html source docs/html -E -A build="pages"
+      - name: Spinx build slides
+        run: |
+            sphinx-build -b html source docs/html/slides -E -A build="slides"
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: 'docs/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -0,0 +1,5 @@
+*.swp
+*.swo
+docs/
+*.nix
+venv/

CONTRIBUTING.md

@@ -0,0 +1,172 @@
+# Contributing to <img src="./source/_static/T4D_logo_bw.svg" alt="T4D GmbH" width="20" height="20">'s `Web Course Template` 📚
+
+Thank you for your interest in contributing to this template!
+
+We appreciate your help in improving this template.
+Please follow the guidelines below to ensure a smooth contribution process.
+
+## General Guidelines 📝
+
+- **Be Respectful**: Treat all contributors with respect and kindness.
+  We are all here to learn and improve.
+- **Read the existing documentation**: Familiarize yourself with the existing content before making changes.
+  This will also help you understand the structure and style.
+- **Use Clear Language**: Aim for clarity and conciseness in your writing.
+  Avoid jargon unless you are using terms that are generally understood.
+
+## Setting Up Your Environment ⚙️
+
+To contribute to this course, you'll need to set up your build environment 🏗️.
+
+Follow these steps:
+
+1. **Clone the Repository**:
+    ```
+    git clone https://github.com/t4d-gmbh/web-course-template
+    cd web-course-template
+    ```
+
+2. **Install Dependencies**:
+   Make sure you have Sphinx installed.
+   You can install it, along with all ohter dependencies using pip:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Build&view the content**
+   To build the content locally, run:
+   ```
+   sphinx-build -b html source docs/html -E -A build="pages"
+   sphinx-build -b html source docs/html/slides -E -A build="slides"
+   ```
+   This will generate the HTML documentation in the `docs/html` directory.
+
+   The first command will build the static html pages and the second command builds the slides 🖼️.
+
+   To browse the html pages locally, open `docs/html/index.html` in your favorite browser.
+   For the slides, open `docs/html/slides/index.html`
+
+   ⚠️ Note ⚠️: The links to switch from the html pages view to the slides view are broken when locally
+   viewing the files.
+
+## Implementing Changes 🛠️
+
+The content is situated under `source/content` and split up into topical sub-folders.
+Each sub-folder should contain an `index.md` that determines which `*.md` files to include.
+The content from the sub-folder is then included in the main content by including its `index.md`
+file in the `toctree` of [`source/index.md`](./source/index.md):
+
+    # source/index.md
+    ...
+    ```{toctree}
+    ...
+    content/<sub-folder>/index
+    ```
+
+### Slide vs. Page Content
+
+The content is rendered both as slides and as html pages.
+Typically, slides should contain illustrations and bullet-point like text snippets while the 
+pages should be somewhat more self-contained.
+
+Since we do not wont to duplicate content we can create markdown files that can be rendered both
+as slides and included into the static view of html pages.
+To achieve this we render all the markdown content with `jinja` before converting it to `html` and
+pass a `build` context variable along that is either set to `"slides"` or `"pages"`.
+
+Following this procedure we then setup the `index.md` file in each sub(-sub)-folder as follows:
+
+
+    {% if build == "slides" %}
+    <!-- BUILDING THE SLIDES -->
+    ```{toctree}
+    :maxdepth: 2
+    :caption: Contents
+
+    ./slide1
+    ./slide2
+    ...
+    ```
+    {% else %}
+    <!-- BUILDING THE PAGES -->
+    ```{include} ./slide1.md
+    ```
+    Maybe some extra text for the pages
+    ```{include} ./slide2.md
+    ```
+    {% endif %}
+
+This will render each slide on a separate page for the slides and build a document
+that includes the slides for the html page.
+Note that we also adapt the styling of the page depending on the value of the `build`
+context variable.
+
+Within each included or imported `.md` file you can also specify what content you want
+to show in the slides and what should be shown in the page view.
+You can use:
+
+- `{% if builds == 'pages' %}...{% endif %}` or `{% if page %}...{% endif %}` to include
+  content only in the static page
+- `{% if builds == 'slides' %}...{% endif %}` or `{% if slide %}...{% endif %}` to include
+  content only in the slide
+
+The above `slide1.md` could look as follows:
+
+    {% if build == "slides" %}
+    # Slide 1 title
+    {% else %}
+    ## Subtitle for slide 1 content
+    {% endif %}
+
+    **This text is both on the slide and in the pages
+    {% if slide %}
+    🤪 This in only on the slide 🤪
+    {% endif %}
+
+    {% if page %}
+    This text is only in the pages view and not on the slide
+    {% endif %}
+
+
+## Making Contributions ✨
+
+Here are some ways you can contribute:
+
+- **Fixing Typos**: Simple fixes like correcting typos or grammatical errors are always welcome!
+- **Improving Clarity**: If you find sections that are unclear, feel free to rewrite them for better understanding.
+- **Adding Examples**: Examples can greatly enhance the documentation. If you have a use case, consider adding it.
+- **Suggest Additions**: If you think that the course is missing come curcial aspects, let us know by [creating an Issue](https://github.com/t4d-gmbh/working-with-git/issues/new).
+
+## Submitting Changes 🚀
+
+Once you have made your changes, follow these steps to submit them:
+
+1. **Create a New Branch**:
+    ```
+    git checkout -b my-feature-branch
+    ```
+
+2. **Commit Your Changes**:
+   Make sure to write clear and descriptive commit messages:
+    ```
+    git commit -m "Fix typo in about git section"
+    ```
+
+3. **Push to Your Fork**:
+    ```
+    git push origin my-feature-branch
+    ```
+
+4. **Open a Pull Request**:
+   Go to the original repository on GitHub and open a pull request.
+   Provide a clear description of your changes and why they are needed.
+
+## Additional Resources 🌐
+
+- [Sphinx Documentation](https://www.sphinx-doc.org/en/master/)
+- [Markdown Guide](https://www.markdownguide.org/)
+- [GitHub Flow](https://guides.github.com/introduction/flow/)
+
+Thank you for contributing!
+Your efforts help make our documentation better for everyone. If you have any questions, feel free to reach out to the maintainers.
+

README.md

@@ -0,0 +1,27 @@
+# Web Course Template
+
+This is <img src="./source/_static/T4D_logo_bw.svg" alt="T4D GmbH" width="20" height="20">'s template for a web-based
+course/workshop content.
+
+Feel free to use it as you please!
+
+## Usage 🧱
+
+You can simply [use this repository as a template](https://github.com/new?template_name=web-course-template&template_owner=t4d-gmbh) for your own project.
+
+The actual content of the web-based course resides in the [`./source/content`](./source/content) folder.
+You will already find some documentation on how to use this template there.
+So consider the content both as 🧭 guideline and 💡 inspiration.
+
+
+<!-- include-upper -->
+
+## Contributing 🤝🎉
+
+We welcome contributions to this template!
+Whether you're fixing bugs 🐛 or typos, adding new features ✨, or improving readability 📚, your help is greatly appreciated!
+
+Before you start, please take a moment to read our [CONTRIBUTING.md](CONTRIBUTING.md) file.
+It contains some details and guidelines 📋 on how to structure new content and best practices to help you get started and ensure that your contributions aligned with the project's goals. 🚀
+
+Thank you for considering contributing to this course! You're awesome! 🌟

requirements.txt

@@ -0,0 +1,9 @@
+sphinx~=8.0.0
+
+sphinx-book-theme==1.1.3
+# pydata-sphinx-theme~=0.15.4
+myst-parser>=4.0.0
+sphinx-favicon>=1.0.1
+sphinx-tabs>=3.4.4
+sphinx_design>=0.5.0
+setuptools_scm~=8.1.0  # for the git versioning