diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..529b88f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,164 @@ +# Contributing to the `working-with-git` course 📚 + +Thank you for your interest in contributing to our documentation! +We appreciate your help in making this course better. +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 course content**: 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/working-with-git + cd working-with-git + ``` + +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. +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 build == "pages" %} + ðŸĪŠ This in only on the slide ðŸĪŠ + {% endif %} + + {% if build == "pages" %} + 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 index c12c565..aba720d 100644 --- a/README.md +++ b/README.md @@ -4,3 +4,13 @@ This is T4D's practical guide for professionals and hobbyists that want to learn [more] about the usage of [git](https://git-scm.com/) and DevOps software like [GitHub](https://github.com) and [GitLab](https://gitlab.com) to develop, track and secure their digital projects. + +## Contributing ðŸĪðŸŽ‰ + +We welcome contributions to this project! +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! 🌟