From a3b35e64717db19f3d9583badf355a9487f19adf Mon Sep 17 00:00:00 2001 From: "Jonas I. Liechti" Date: Thu, 10 Oct 2024 02:26:12 +0200 Subject: [PATCH] initial commit --- .github/workflows/pages.yml | 53 ++++++ .gitignore | 5 + CONTRIBUTING.md | 172 ++++++++++++++++++++ README.md | 27 +++ requirements.txt | 9 + source/_static/T4D_logo_bw.svg | 119 ++++++++++++++ source/_static/T4D_logo_wb.svg | 120 ++++++++++++++ source/_static/custom.css | 26 +++ source/_static/slides.css | 3 + source/_templates/page.html | 45 +++++ source/conf.py | 131 +++++++++++++++ source/content/examples/index.md | 20 +++ source/content/examples/working-with-git.md | 5 + source/content/howto/combining.md | 22 +++ source/content/howto/conditional_content.md | 27 +++ source/content/howto/index.md | 22 +++ source/content/howto/structure.md | 7 + source/content/index.md | 6 + source/index.md | 10 ++ 19 files changed, 829 insertions(+) create mode 100644 .github/workflows/pages.yml create mode 100644 .gitignore create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 requirements.txt create mode 100644 source/_static/T4D_logo_bw.svg create mode 100644 source/_static/T4D_logo_wb.svg create mode 100644 source/_static/custom.css create mode 100644 source/_static/slides.css create mode 100644 source/_templates/page.html create mode 100644 source/conf.py create mode 100644 source/content/examples/index.md create mode 100644 source/content/examples/working-with-git.md create mode 100644 source/content/howto/combining.md create mode 100644 source/content/howto/conditional_content.md create mode 100644 source/content/howto/index.md create mode 100644 source/content/howto/structure.md create mode 100644 source/content/index.md create mode 100644 source/index.md diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..86fc8cd --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..307502b --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +*.swp +*.swo +docs/ +*.nix +venv/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..dec1cca --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,172 @@ +# Contributing to T4D GmbH'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//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" %} + + ```{toctree} + :maxdepth: 2 + :caption: Contents + + ./slide1 + ./slide2 + ... + ``` + {% else %} + + ```{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. + diff --git a/README.md b/README.md new file mode 100644 index 0000000..b3b07fd --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ +# Web Course Template + +This is T4D GmbH'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. + + + + +## 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! 🌟 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..95dfcaa --- /dev/null +++ b/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 diff --git a/source/_static/T4D_logo_bw.svg b/source/_static/T4D_logo_bw.svg new file mode 100644 index 0000000..cd276b9 --- /dev/null +++ b/source/_static/T4D_logo_bw.svg @@ -0,0 +1,119 @@ + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/source/_static/T4D_logo_wb.svg b/source/_static/T4D_logo_wb.svg new file mode 100644 index 0000000..63e9c56 --- /dev/null +++ b/source/_static/T4D_logo_wb.svg @@ -0,0 +1,120 @@ + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/source/_static/custom.css b/source/_static/custom.css new file mode 100644 index 0000000..ae3db38 --- /dev/null +++ b/source/_static/custom.css @@ -0,0 +1,26 @@ +/* Just some suggestion on what colors to use for git commands */ + +.pull { + color: red; +} +.push { + color: darkviolet; +} +.commit{ + color: blue; +} +.fetch{ + color: green; +} +.clone{ + color: #ca80e9; +} +.merge{ + color: lightgreen; +} +.rebase{ + color: orange; +} +.add{ + color: gray; +} diff --git a/source/_static/slides.css b/source/_static/slides.css new file mode 100644 index 0000000..2f6dbd4 --- /dev/null +++ b/source/_static/slides.css @@ -0,0 +1,3 @@ +.bd-page-width { + max-width: max(88rem, 85vw); +} diff --git a/source/_templates/page.html b/source/_templates/page.html new file mode 100644 index 0000000..ad8541a --- /dev/null +++ b/source/_templates/page.html @@ -0,0 +1,45 @@ +{% extends "!layout.html" %} + +{% block body %} + +{% if build == "slides" %} +
+
+ {{ body }} +
+
+ + + +{% else %} + {{ body }} +{% endif %} +{% endblock %} diff --git a/source/conf.py b/source/conf.py new file mode 100644 index 0000000..61a46b1 --- /dev/null +++ b/source/conf.py @@ -0,0 +1,131 @@ +from setuptools_scm import get_version + +# ### +# Versioning - get it from the git tag +# ### +version: str = get_version(root='..') +release = version + +# ### +# Basic Project info +# ### +project = 'Web Course Template' +copyright = '2023-2024, T4D GmbH' +author = 'Jonas Liechti - https://github.com/j-i-l' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "myst_parser", + "sphinx_favicon", + "sphinx_design", + "sphinx_tabs.tabs", +] + +templates_path = ['_templates'] +exclude_patterns = [] + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_book_theme' +html_static_path = ['_static'] +html_css_files = ['custom.css',] + +html_context = { + "default_mode": "light", +} + +discuss_icon = { + "name": "GitHub Discussion", + "url": "https://github.com/t4d-gmbh/working-with-git/discussions", + "icon": "fa-regular fa-comments", + "type": "fontawesome", + } +pages_icon = { + "name": "Pages", + "url": "https://t4d-gmbh.github.io/working-with-git/index.html", + "icon": "fa-solid fa-book", + "type": "fontawesome", + } +slides_icon = { + "name": "Slides", + "url": "https://t4d-gmbh.github.io/working-with-git/slides/index.html", + "icon": "fa-solid fa-person-chalkboard", + "type": "fontawesome", + } +html_theme_options = { + "repository_url": "https://github.com/t4d-gmbh/working-with-git", + "repository_branch": "main", + "path_to_docs": "source/", + "use_edit_page_button": True, + "use_repository_button": True, + "toc_title": "Content", + "use_sidenotes": True, + "logo": { + "text": "T4D GmbH", + "image_light": "_static/T4D_logo_bw.svg", + "image_dark": "_static/T4D_logo_wb.svg", + "link": "https://github.com/t4d-gmbh", + }, + "show_toc_level": 2, # Show the table of contents up to level 2 + "navigation_with_keys": True, # Enable keyboard navigation + "collapse_navigation": False, # Do not collapse the navigation + # "sidebar_width": "250px", # Set the width of the sidebar + "icon_links": [discuss_icon, slides_icon], +} + +favicons = [ + "_static/T4D_logo_bw.svg" +] + +myst_enable_extensions = [ + "colon_fence", +] + +# ### +# Custom jinja parser to enable jinja templating +# ### +def rstjinja(app, docname, source): + """ + Render source file with jinja first + """ + print(f"{docname=}") + # only apply to 'html' builder + if app.builder.format == 'html': + src = source[0] + rendered = app.builder.templates.render_string( + src, app.config.html_context + ) + source[0] = rendered + +def include_rstjinja(app, docname, parent_docname, source): + return rstjinja(app=app, docname=docname, source=source) + +def setup(app): + builds = app.config.html_context.get('build', 'pages') + # setting `slide` and `page` context + app.config.html_context['page'] = True + app.config.html_context['slide'] = False + if builds == 'slides': + app.config.html_context['slide'] = True + app.config.html_context['page'] = False + # ### + # we do some config adaptations for the slides + # ### + # simpler sidebar + app.config.html_sidebars = { + "**": [ + # "navbar-logo.html", + "icon-links.html", + # "search-button-field.html", + "sbt-sidebar-nav.html" + ] + } + # only show discuss and pages icons in sidebar + app.config.html_theme_options['icon_links'] = [discuss_icon, pages_icon] + # adding the new styling + app.config.html_css_files.append('slides.css') + app.connect("source-read", rstjinja) + app.connect("include-read", include_rstjinja) diff --git a/source/content/examples/index.md b/source/content/examples/index.md new file mode 100644 index 0000000..756aaa0 --- /dev/null +++ b/source/content/examples/index.md @@ -0,0 +1,20 @@ +# Examples + +Here you can find some projects that use this template: + +{% if build == "slides" %} + +```{toctree} +:maxdepth: 2 +:caption: Examples + +./working-with-git +./combining +./conditional_content +``` +{% else %} + +```{include} ./working-with-git.md +``` +{% endif %} + diff --git a/source/content/examples/working-with-git.md b/source/content/examples/working-with-git.md new file mode 100644 index 0000000..b2d4e97 --- /dev/null +++ b/source/content/examples/working-with-git.md @@ -0,0 +1,5 @@ +# Working-with-git + +https://github.com/t4d-gmbh/working-with-git + +https://t4d-gmbh.github.io/working-with-git/ diff --git a/source/content/howto/combining.md b/source/content/howto/combining.md new file mode 100644 index 0000000..4849f99 --- /dev/null +++ b/source/content/howto/combining.md @@ -0,0 +1,22 @@ +## Combining Content + +We want to display each slide as a separate site but combine several slides into a single static webpage. + +To do so we can use the following pattern in each`index.md` file of a sub-folder in `source/content`: + + \{% if build == "slides" %\} + + ```{toctree} + :maxdepth: 2 + :caption: MySubSection + + ./slide1 + ./slide2 + ``` + \{% else %\} + + ```{include} ./slide1.md + ``` + ```{include} ./slide2.md + ``` + \{% endif %\} diff --git a/source/content/howto/conditional_content.md b/source/content/howto/conditional_content.md new file mode 100644 index 0000000..22edc2f --- /dev/null +++ b/source/content/howto/conditional_content.md @@ -0,0 +1,27 @@ +## Conditional Content + +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 %} diff --git a/source/content/howto/index.md b/source/content/howto/index.md new file mode 100644 index 0000000..3b1391a --- /dev/null +++ b/source/content/howto/index.md @@ -0,0 +1,22 @@ +# How-To + +{% if build == "slides" %} + +```{toctree} +:maxdepth: 2 +:caption: How-To + +./structure +./combining +./conditional_content +``` +{% else %} + +```{include} ./structure.md +``` +```{include} ./combining.md +``` +```{include} ./conditional_content.md +``` +{% endif %} + diff --git a/source/content/howto/structure.md b/source/content/howto/structure.md new file mode 100644 index 0000000..69d972e --- /dev/null +++ b/source/content/howto/structure.md @@ -0,0 +1,7 @@ +## Content Structure + +The following 📜 principles apply: + +- For each section of your content create a new sub-folder under `source/content` +- Each sub-folder should contain an `index.md` file +- ... diff --git a/source/content/index.md b/source/content/index.md new file mode 100644 index 0000000..1a1111e --- /dev/null +++ b/source/content/index.md @@ -0,0 +1,6 @@ +```{toctree} +:maxdepth: {% if build == "slides" %}1{% else %}2{% endif %} + +howto/index +examples/index +``` diff --git a/source/index.md b/source/index.md new file mode 100644 index 0000000..4622b3b --- /dev/null +++ b/source/index.md @@ -0,0 +1,10 @@ +```{include} ../README.md +:end-before: +``` +```{toctree} +:maxdepth: 2 +{% if build == "slides" %}:numbered:{% endif %} +:caption: Course Template Docs + +content/index +```