Merge pull request #72 from rl-institut/feature-34-docs

Update documentation #34

CHANGELOG.md

@@ -39,6 +39,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Update GitHub Action for develop branch [(#58)](https://github.com/rl-institut/super-repository/pull/58)
 - Update the sections and merge subpages of the documentation [(#62)](https://github.com/rl-institut/super-repository/pull/62)
 - Update documentation for release [(#69)](https://github.com/rl-institut/super-repository/pull/69)
+- Update documentation best-practices [(#72)](https://github.com/rl-institut/super-repository/pull/72)
 
 ### Removed
 

docs/code/style/index.md → docs/development/best-practice/code_style.md

@@ -8,22 +8,21 @@ Maintaining a consistent code style is crucial for the readability and
 maintainability of a Python project.
 
 We enforce most of the following guidelines in our
-[Continuous-Integration pipeline](../../development/continuous-integration/index.md)
+[Continuous-Integration pipeline](https://rl-institut.github.io/super-repository/develop/development/continuous-integration/)
 that check the code automatically.
 
 ## 1. Installation
 
 Before contributing to the project, make sure you have the necessary tools
 installed for code style enforcement.
-We utilize [pre-commit](https://github.com/pre-commit/pre-commit-hooks)
+We utilize [pre-commit](https://rl-institut.github.io/super-repository/develop/development/continuous-integration/)
 to automate code checks before committing changes.
-To install and setup pre-commit, see [Continuous-Integration pipeline](../../development/git/#pre-commit)
 
 ## 2. Code Formatting
 
 Consistent code formatting enhances readability and reduces unnecessary
 debates about style.
-We use [Black](https://github.com/psf/black) as our Python code formatter.
+We use [Ruff](https://github.com/astral-sh/ruff) as Python code formatter.
 It automatically formats your code to adhere to the project's style guidelines.
 
 ## 3. Naming Conventions
@@ -45,14 +44,7 @@ Use comments to explain complex logic and docstrings to describe functions,
 classes, and modules.
 Following good documentation practices ensures code is understandable to others.
 
-## 6. Imports
-
-Our imports are automatically checked and sorted using
-[isort](https://github.com/pycqa/isort).
-This tool organizes imports based on the Black code style and optimizes import
-statements for readability.
-
-## 7. Code Structure and Organization
+## 6. Code Structure and Organization
 
 Maintain a logical structure within files, grouping related functions and
 classes. Consider the readability of your code and strive for modular,

docs/development/best-practice/continuous_integration.md

@@ -0,0 +1,128 @@
+# Continuous Integration (CI) and Test Automation
+
+Continuous Integration (CI) ensures consistent code quality through automated
+testing, reporting, and deployments. <br>
+Our setup combines `GitHub Actions` and `tox` to streamline testing across
+environments, making the process robust and efficient.
+
+## GitHub Actions: Workflows
+
+GitHub Actions automates key workflows like testing, linting, and code
+quality checks. The CI pipeline includes the following tasks:  
+- **Unit Testing**: Using `pytest` to ensure comprehensive test coverage.  
+- **Code Formatting**: Validating syntax with `ruff`.  
+- **Linting**: Verifying code style and docstrings with `ruff.lint`.
+- **Import Sorting**: Organizing imports with `ruff.lint.isort`.  
+
+To set up GitHub Actions workflows for the repository,
+follow the [official GitHub guide](https://docs.github.com/en/actions/guides).<br>
+The GitHub Actions workflow is triggered on pull requests or commits to
+the `develop` or `production` branches.  
+1. **Setup**: Prepares a Python environment and installs dependencies.  
+2. **Testing**: Executes the `tox` automation suite to run the defined tests.  
+3. **Reporting**: Generates detailed failure reports for debugging.  
+
+GitHub Actions also automates documentation updates, ensuring the latest
+changes from the `develop` branch are reflected. For more details, see
+the [official GitHub Actions guide](https://docs.github.com/en/actions/guides).
+
+
+## Tox: Automating Testing
+
+[`tox`](https://tox.wiki/en/stable/) is a versatile tool for managing test
+environments and automating testing tasks across Python versions and operating
+systems (Linux, macOS, Windows). <br>
+It enhances reproducibility and reliability by creating isolated environments
+for testing:
+
+- **Virtual Environments**: Isolates dependencies for each Python version.  
+- **Automated Testing**: Runs tests and style checks (for example, `pytest`, `ruff`).  
+- **Cross-Version/Platform Testing**: Ensures compatibility across Python versions and operating systems.  
+- **Dependency Management**: Customizes dependencies for diverse test scenarios.  
+- **Reproducibility**: Maintains consistent workflows by way of 📝 `tox.ini`.  
+- **Extensibility**: Supports plugins for custom functionality.
+
+### Install
+
+Install the required package in a python environment. <br>
+💻 `pip install tox` install tox <br>
+💻 `tox` run tox locally
+
+
+## Adding and Managing Tests
+
+New tests should be placed in the 📝 `tests/` directory. For example:  
+- Add a test to validate new functionality.  
+- Use `pytest` for unit tests, or extend 📝 `tox.ini` for additional test configurations.  
+
+By combining `tox` and GitHub Actions, our CI pipeline ensures robust,
+reproducible, and scalable testing workflows.
+
+### Test Patterns
+
+1. **Unit and Integration Test**
+   - **Purpose**: Test individual functions or methods.
+   - **Framework**: `unittest`, `pytest`
+   - **Example**: Simple function test and external API interactions.
+
+2. **Functional Testing**
+   - **Purpose**: Test complete functionality (end-to-end).
+   - **Framework**: `pytest`, `selenium`
+   - **Example**: Test user login in a web app.
+
+3. **Mocking**
+   - **Purpose**: Simulate external dependencies.
+   - **Framework**: `unittest.mock`, `pytest-mock`
+   - **Example**: Mock API calls in tests.
+
+4. **Acceptance Testing**
+   - **Purpose**: Verify the software meets requirements.
+   - **Framework**: `pytest`, `Behave`
+   - **Example**: Verify login form functionality.
+
+5. **Performance Testing**
+   - **Purpose**: Measure performance under load.
+   - **Framework**: `pytest-benchmark`, `locust`
+   - **Example**: Measure function execution time.
+
+6. **Security Testing**
+    - **Purpose**: Test for security vulnerabilities.
+    - **Framework**: `bandit`
+    - **Example**: Scan for hardcoded passwords.
+
+7. **Snapshot Testing**
+    - **Purpose**: Compare outputs to saved snapshots.
+    - **Framework**: `pytest-snapshot`
+    - **Example**: Compare function output snapshots.
+
+8. **Property-Based Testing**
+    - **Purpose**: Test properties of functions with random inputs.
+    - **Framework**: `hypothesis`
+    - **Example**: Test that a sorting function always returns a sorted list.
+
+### Examples
+
+The file 📝 `tests/test_example.py` contains basic examples for the functions in <br>
+📝 `super_repo/test_calculator.py`.
+
+In Python, the `assert` statement is used to test if a condition is true. <br>
+If the condition is false, an AssertionError is raised, indicating the test failed.
+
+```python
+result = add(3, 4)
+assert result == 7
+```
+
+The `raises` context manager from the `pytest` library ensures that a ValueError is raised. <br>
+The `match` argument specifies that the error message matches the expected error pattern.
+
+```python
+with raises(ValueError, match=r"Cannot divide by zero"):
+    divide(15, 0)
+```
+
+We encourage contributions of additional tests and examples to help improve
+coverage and showcase different use cases—your input is valuable to enhancing the project!
+
+!!! note "Used Icons"
+    🐙 GitHub | 💠 git | 📝 File | 💻 Command Line

docs/development/best-practice/index.md

@@ -0,0 +1,23 @@
+# Best Practices
+
+Adopting best practices in software development enhances code quality,
+maintains consistency, and ensures reliability. <br>
+This section focuses on three key methodologies essential for maintaining
+high standards in a collaborative scientific software environment:
+
+- [**Continuous Integration (CI)**](https://rl-institut.github.io/super-repository/develop/development/continuous-integration/): <br>
+  Automating the integration of code changes to catch errors early and maintain a stable codebase.
+  CI ensures that all contributions are rigorously tested and integrated seamlessly into the project.
+
+- [**Test-Driven Development (TDD)**](https://rl-institut.github.io/super-repository/develop/development/continuous-integration/): <br>
+  A methodology where tests are written before the actual code implementation. <br>
+  TDD promotes robust and well-designed code by enforcing that each feature is accompanied by
+  thorough testing from the outset.
+
+- [**Pre-commit Hooks (PCH)**](https://rl-institut.github.io/super-repository/develop/development/continuous-integration/): <br>
+  Tools to enforce code
+  quality and consistency by running checks or scripts before changes are committed. <br>
+  These hooks help identify issues early, improving code hygiene and reducing technical debt.
+
+Following these practices will streamline development, reduce bugs, and foster a
+productive, collaborative coding environment.

docs/development/best-practice/pre_commit_hooks.md

@@ -0,0 +1,25 @@
+# Pre-commit Hooks
+
+Pre-commit hooks are tools used to enforce code quality and consistency by <br>
+running checks or scripts before changes are committed. <br>
+These hooks help identify issues early, improving code hygiene.
+
+## Installation and Setup
+
+Install the package in your base environment.
+   💻 `pip install pre-commit`
+
+Create a 📝 `.pre-commit-config.yaml` file in your repository root. <br>
+This file defines the hooks and configurations.
+
+## Usage
+
+To run the hooks manually, use: <br>
+   💻 `pre-commit run --all-files`
+
+Now, every time you commit changes, the pre-commit hooks will automatically <br>
+run the checks defined in your configuration file, ensuring code quality before
+committing.
+
+!!! note "Used Icons"
+    🐙 GitHub | 💠 git | 📝 File | 💻 Command Line