Merge pull request #62 from rl-institut/feature-1-docs-navigation

Update the sections and merge subpages of the documentation

.github/ISSUE_TEMPLATE/issue_template_bug.md

@@ -2,7 +2,7 @@
 name: Bug Issue
 about: For bugs and errors
 title: Your title should make sense if said after "The issue is <your issue title>"
-labels: "bug"
+labels: ["status: active :construction:", "type: bug :bug:"]
 assignees: ""
 ---
 

.github/ISSUE_TEMPLATE/issue_template_feature.md

@@ -2,7 +2,7 @@
 name: Feature Issue
 about: For new ideas, developments and features
 title: Your title should make sense if said after "The issue is <your issue title>"
-labels: "enhancement"
+labels: ["status: active :construction:", "type: feature :hammer_and_wrench:"]
 assignees: ""
 ---
 

.github/ISSUE_TEMPLATE/issue_template_release.md

@@ -2,7 +2,13 @@
 name: Release Issue
 about: For a new release
 title: Release - Minor Version - 0.1.0
-labels: "enhancement"
+labels:
+  [
+    "priority: critical :fire:",
+    "status: active :construction:",
+    "type: release :rocket:",
+    "part: github :octocat:",
+  ]
 assignees: "Ludee"
 ---
 

CHANGELOG.md

@@ -21,10 +21,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update CSS to improve toc [(#54)](https://github.com/rl-institut/super-repo/pull/54)
 - Update documentation for mike [(#54)](https://github.com/rl-institut/super-repo/pull/54)
 - Update GitHub Action for develop branch [(#58)](https://github.com/rl-institut/super-repo/pull/58)
+- Update the sections and merge subpages of the documentation [(#62)](https://github.com/rl-institut/super-repo/pull/62)
 
 ### Removed
 
 - Disable GitHub Action for MkDocs Workflow [(#54)](https://github.com/rl-institut/super-repo/pull/54)
+- Remove merged documentation files [(#62)](https://github.com/rl-institut/super-repo/pull/62)
 
 ## [0.2.0] Minor Release - Oh Hi Mike - 2023-08-11
 

CONTRIBUTING.md

@@ -31,7 +31,7 @@ If you wish, add your name and details to `CITATION.cff`.
 You add code and become an author of the repository.
 You must follow the workflow!
 
-### D. Mantain and Release
+### D. Maintain and Release
 
 You contribute and take care of the repository.
 You review and answer questions.
@@ -44,10 +44,12 @@ The workflow for contributing to this project has been inspired by the workflow
 ### 1. Describe the issue on GitHub
 
 Create [an issue](https://help.github.com/en/articles/creating-an-issue)
-in the GitHub repository.
-The `issue title` describes the problem you will address. <br>
-This is an important step as it forces one to think about the "issue".
-Make a checklist for all needed steps if possible.
+in the GitHub repository. <br>
+Choose a suitable [issue template](https://rl-institut.github.io/super-repo/develop/development/git/)
+for a `feature` or a `bug` and fill in as much information as possible.
+Most important is the `issue title`, it describes the problem you will address. <br>
+Update the `GitHub Labels` and assign to a `GitHub Project` and `Milestone` <br>
+Creating the issue an important step as it forces one to think about the "issue".
 
 ### 2. Solve the issue locally
 
@@ -83,7 +85,7 @@ Naming convention for branches: `type`-`issue-nr`-`short-description`
 ##### `type`
 
 - feature - includes the feature that will be implemented
-- hotfix - includes small improvements before an release, should be branched from a release branch
+- hotfix - includes small improvements before a release, should be branched from a release branch
 - release - includes the current version to be released
 
 The majority of the development will be done in `feature` branches.

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Reiner Lemoine Institut
+Copyright © Reiner Lemoine Institut
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

docs/development/collaboration/chat.md

@@ -2,10 +2,11 @@
 
 For direct communication, this repo uses a public [Element](https://element.io/) room. <br>
 This messenger platform is based on the [[matrix]](https://en.wikipedia.org/wiki/Matrix_(protocol))
-communication protocol and can be accessed without a mobile phone.
+communication protocol <br>
+and can be accessed without a mobile phone.
 
-To engage with the developer and user community, login with an existing account
-(e.g. GitHub) or register a new account.
+To engage with the developer and user community, <br>
+login with an existing account (e.g. GitHub) or register a new account.
 
 The room name is:
 [Super-Repo:matrix.org](https://app.element.io/#/room/#super-repo:matrix.org). <br>

docs/development/collaboration/code_of_conduct.md

@@ -1,4 +1,7 @@
 # Code of Conduct
 
 This repository is following the [Contributor Covenant Code of Conduct](https://github.com/rl-institut/super-repo/blob/production/CODE_OF_CONDUCT.md). <br>
-Everyone is asked to be self-reflective and always maintain a good culture of discussion and active participation.
+
+Everyone is asked to be self-reflective and always maintain a good culture
+of discussion and active participation.
+This includes written communication in this repo and direct encounters in meetings and events.

docs/development/collaboration/license_and_citation.md

@@ -0,0 +1,30 @@
+# License
+
+This software is developed under an
+[open-source license](https://en.wikipedia.org/wiki/Open-source_license). <br>
+The selected license can be read in the
+[LICENSE.txt](https://github.com/rl-institut/super-repo/blob/production/LICENSE.txt).
+
+## [MIT License]
+
+The users have permission to
+[run and use, modify, distribute the program, and release the improvements](https://www.gnu.de/free-software/index.de.html)
+as long as you follow the license obligations to give a proper attribution and
+include the license text.
+
+Please attribute as:
+
+**"Super-Repo" © Reiner Lemoine Institut | MIT License**
+
+# Citation
+
+To [scientifically cite](https://en.wikipedia.org/wiki/Quotation) this
+repository, see the **_Cite this repository_** function or the file
+[CITATION.cff](https://github.com/rl-institut/super-repo/blob/production/CITATION.cff).
+
+# Contributing
+
+Since this software is under an open source license and can be downloaded,
+run and modified, you are invited to comment, improve and develop the program as you wish. <br>
+To contribute to the **collaborative development** follow the workflow described in
+[CONTRIBUTING.md](https://github.com/rl-institut/super-repo/blob/production/CONTRIBUTING.md).

docs/development/git/index.md

@@ -1,10 +1,90 @@
 # Git
 
-- .gitignore
+## Branches
 
-Copied from (A collection of useful .gitignore templates)[https://github.com/github/gitignore]. <br>
-For more information about how `.gitignore` files work, and how to use them, see (Ignoring Files chapter)[https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring] of the Pro Git book.
+[Git Branches](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches)
+are used to structure the developments and improvements.
 
-- issue_template
-- pull_request_template
-- workflows (testing)
+### Permanent Branches
+
+- **production** - includes the current stable (latest) version
+- **develop** - includes all current developments
+
+### Temporary Branches
+
+- **feature** - includes the feature and improvements that will be implemented
+- **hotfix** - includes small improvements before a release, should be branched from a release branch
+- **release** - includes the current version to be released
+
+The majority of the development will be done in `feature` branches.
+
+## Gitignore
+
+This file specifies intentionally untracked files to ignore.
+It is copied from [a collection of .gitignore templates](https://github.com/github/gitignore). <br>
+For more information about how `.gitignore` files work, see the [Ignoring Files chapter](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring) of the Pro Git book.
+
+## Issue Templates
+
+[Issue Templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)
+offer specific functions and default configurations for new issues.
+
+- [Feature Issue](https://github.com/rl-institut/super-repo/blob/production/.github/ISSUE_TEMPLATE/issue_template_feature.md)
+- [Bug Issue](https://github.com/rl-institut/super-repo/blob/production/.github/ISSUE_TEMPLATE/issue_template_bug.md)
+- [Release Issue](https://github.com/rl-institut/super-repo/blob/production/.github/ISSUE_TEMPLATE/issue_template_release.md)
+
+## Pull Request (PR) Template
+
+The [Pull Request Template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/creating-a-pull-request-template-for-your-repository)
+is used for all PR, because it is only possible to create a single one.
+It includes all needed information to merge branches and release new versions.
+
+## GitHub Workflows (Actions)
+
+[GitHub Actions](https://github.com/rl-institut/super-repo/actions)
+are used to automate processes of the repository. <br>
+Main use-cases are building and publishing the documentation and run automated tests.
+
+## Pre-commit
+
+**Pre-commit** is a tool to easily setup and run `pre-commit hooks` for your git repository.<br>
+See the documentation of [pre-commit](https://pre-commit.com/) for further information.<br>
+It is used to improve auto-format code, do linting and run tests before every commit.
+
+### Install
+
+Install the required package in a python environment. <br>
+💻 `pip install pre-commit` install pre-commit <br>
+💻 `pre-commit install` install pre-commit
+
+### Setup
+
+The hooks are configured in the `.pre-commit-config.yaml` file.<br>
+List of implemented hooks:
+
+- [Pre-commit-hooks](https://github.com/pre-commit/pre-commit-hooks) - Out-of-the-box hooks
+- [Black](https://github.com/psf/black) - Python code formatter
+- [isort](https://github.com/pycqa/isort) - Sort Python imports
+- [Ruff](https://github.com/astral-sh/ruff-pre-commit) - Fast Python linter, written in Rust
+- [Flake8](https://github.com/pycqa/flake8) - Python linter with PyFlakes and pycodestyle
+- [mypy mirror](https://github.com/pre-commit/mirrors-mypy) - Added static types to Python
+- [mirrors-prettier](https://github.com/pre-commit/mirrors-prettier) - Formatting for other files then python scripts
+
+### Use
+
+All commits will trigger the hooks automatically.<br>
+💠 `git commit file -m "Commit message #IssueNr"` to commit
+
+Commit without running the hooks.<br>
+💠 `git commit --no-verify file` to commit without hooks
+
+!!! note "Line endings"
+    There can be problems with file line endings on Windows, `CRLF` is used on Windows and `LF` is used on Linux.
+
+To run the hooks on all files in your repository use:<br>
+💻 `pre-commit run --all-files`
+
+!!! warning "Markdown files / Admonitions"
+    If the hook is applied to markdown files that include special formatting,
+    (e.g. `mkdocs.yml`), this can introduce incorrect changes. <br>
+    This effects [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) boxes for MkDocs.

mkdocs.yml

@@ -38,10 +38,11 @@ theme:
 
 # extensions
 markdown_extensions:
-  - admonition
   - toc:
       permalink: "#"
+  - admonition
   - pymdownx.superfences
+  - pymdownx.details
   - pymdownx.highlight:
       use_pygments: true
 
@@ -63,9 +64,7 @@ nav:
   - Development:
     - Collaboration:
       - development/collaboration/index.md
-      - License: development/collaboration/license.md
-      - Citation: development/collaboration/citation.md
-      - Contributing: development/collaboration/contributing.md
+      - License and Citation: development/collaboration/license_and_citation.md
       - Users: development/collaboration/users.md
       - Chat: development/collaboration/chat.md
       - Meetings: development/collaboration/meeting.md