New docs-dev pages

docs-dev/usage-of-black.rst → docs-dev/guider-of-black.rst

@@ -1,16 +1,17 @@
 Black Guide
 ==========================
 
-Black is a code formatter for Python that automatically reformats your code to be more readable and standardized. This guide provides essential information for using Black within this project.
+Black is a code formatter for Python that automatically reformats your code to ensure readability and standardization. This guide explains how to use Black within the project, considering its integration with Poetry and GitHub Actions.
 
 Installation
 ------------
 
-To install Black, use pip:
+Black is already included in the project's development dependencies through Poetry. After running ``poetry install``, Black will be available in the project's virtual environment.
 
-.. code-block:: bash
+.. note::
+
+    There is no need to install Black manually, as it is managed via Poetry.
 
-    pip install black   
 
 Basic Usage
 -----------
@@ -19,17 +20,19 @@ To format all Python files in your project, run the following command from the r
 
 .. code-block:: bash
 
-    black .
+    poetry run black .
 
 This command applies Black's formatting rules to all ``.py`` files in the directory and its subdirectories.
 
-### Formatting a Specific File
+Formatting a Specific File
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To format a specific file, specify the filename:
 
 .. code-block:: bash
 
-    black path/to/your_file.py  
+    poetry run black path/to/your_file.py  
+
 
 Common Options
 --------------
@@ -38,61 +41,68 @@ Common Options
 
     .. code-block:: bash
 
-        black --check .
+        poetry run black --check .
 
 - **Line Length**: By default, Black limits lines to 88 characters. You can set a different line length:
 
     .. code-block:: bash
 
-        black --line-length 100 .
+        poetry run black --line-length 100 .
 
 - **Exclude Files**: To exclude specific files or directories from formatting, use:
 
     .. code-block:: bash
 
-        black --exclude "migrations|env" .
+        poetry run black --exclude "migrations|env" .
+
+
+Integration with CI/CD
+----------------------
+
+Black is an integral part of the project's CI/CD pipeline managed through GitHub Actions. This ensures that all code pushed to the repository adheres to the project's formatting standards. 
+
+.. important::
+
+    Always run ``poetry run black`` locally before committing changes to avoid inconsistencies during the CI/CD process.
+
 
 Integrating Black with Pre-Commit Hooks
 ---------------------------------------
 
-To ensure consistent formatting before commits, you can set up a pre-commit hook.
+To ensure consistent formatting before commits, you can set up a pre-commit hook. The pre-commit hook ensures all staged files are formatted with Black.
 
-1. First, install ``pre-commit`` if it's not already installed:
+1. First, ensure ``pre-commit`` is installed via Poetry:
 
     .. code-block:: bash
 
-        pip install pre-commit
+        poetry add --group dev pre-commit
 
 2. Then, create a ``.pre-commit-config.yaml`` file in the root directory with this content:
 
     .. code-block:: yaml
 
         repos:
         - repo: https://github.com/psf/black
-            rev: 23.1.0  # Use the latest Black version
-            hooks:
-            - id: black
+          rev: 23.1.0  # Use the latest Black version
+          hooks:
+          - id: black
 
 3. Install the hook:
 
     .. code-block:: bash
 
-        pre-commit install
+        poetry run pre-commit install
 
 With this setup, Black will automatically format your code before each commit.
 
 Tips for Working with Black
 ---------------------------
 
 - **Consistency**: Black enforces a uniform style, helping keep code consistent across the project.
-- **Automation**: Use Black in your CI/CD pipeline to automate code style checks.
-- **Editor Integration**: Black is supported by most IDEs and editors, including VS Code and PyCharm.
+- **Automation**: Black is part of the CI/CD pipeline, ensuring all pushed code is formatted correctly.
+- **Editor Integration**: Black is supported by most IDEs and editors, including VS Code and PyCharm. Configure your editor to format files automatically with Black.
 
 Further Documentation
 ----------------------
 
 For more options and detailed documentation, visit the `Black GitHub repository <https://github.com/psf/black>`_.
-
----
-
-By following this guide, you can maintain a clean, readable, and standardized codebase using Black.

docs-dev/usage-of-branching.rst → docs-dev/guider-of-branching.rst

@@ -6,23 +6,26 @@ This project follows a structured branching strategy to manage different version
 Branches
 --------
 
-### Main Branch: ``main``
+Main Branch: ``main``
+---------------------
 
 The ``main`` branch represents the stable, production-ready version of the codebase. It contains the latest official release of the project. Code in ``main`` is fully tested and approved for production use.
 
 - **Current Version**: 2.4.3
 - **Purpose**: Serves as the default branch for stable releases.
 - **Merge Strategy**: Only merges from fully tested and verified branches (such as ``development``) are allowed.
 
-### Development Branch: ``development``
+Development Branch: ``development``
+-----------------------------------
 
 The ``development`` branch is where active development for minor versions takes place. Features, bug fixes, and improvements for the upcoming stable release are integrated here before they are fully tested and merged into ``main``.
 
 - **Current Version**: 2.4.4 (in-progress)
 - **Purpose**: Acts as the integration branch for ongoing work and testing of the next stable release.
 - **Merge Strategy**: Developers create feature branches off ``development`` and merge completed features back into ``development`` after testing.
 
-### Feature Branch: ``dev-3.0.0``
+Feature Branch: ``dev-3.0.0``
+-----------------------------
 
 The ``dev-3.0.0`` branch is dedicated to developing and testing major updates or changes that are not yet stable enough for integration with ``main``. This branch includes work on significant new features and alterations, such as the introduction of new data sources and schema changes in the database.
 
@@ -31,20 +34,47 @@ The ``dev-3.0.0`` branch is dedicated to developing and testing major updates or
 - **Merge Strategy**: Only merged into ``main`` after extensive testing and stability checks. May include code merged from ``development`` if the major version requires updates from minor releases.
 - **Versioning Note**: This branch was initially created from version 2.4.3. Any updates beyond 2.4.3 should be reflected in this branch to maintain continuity.
 
+Documentation Branch: ``gh-pages``
+----------------------------------
+
+The ``gh-pages`` branch is a dedicated branch used exclusively for hosting the development documentation of the project. This branch is managed automatically by GitHub Actions, and its content is regenerated every time a new commit is pushed to the ``development`` branch.
+
+- **Purpose**: Hosts the HTML files generated by Sphinx for the developer documentation.
+- **Restrictions**:
+    - **Do Not Edit Directly**: The branch is overwritten automatically during each deployment. Any manual changes to this branch will be lost.
+    - All updates to the documentation must be made in the ``docs-dev`` directory on the ``development`` branch. The GitHub Actions workflow then builds and deploys these changes to the ``gh-pages`` branch.
+- **Access**: The documentation can be accessed at:
+    [https://ritchielab.github.io/biofilter/](https://ritchielab.github.io/biofilter/)
+
+Workflow for Updating Documentation
+-----------------------------------
+
+1. Make changes to the documentation in the ``docs-dev`` directory in the ``development`` branch.
+2. Commit and push your changes to the ``development`` branch.
+3. GitHub Actions will automatically:
+    - Build the documentation using Sphinx.
+    - Deploy the generated HTML files to the ``gh-pages`` branch.
+4. Verify the updated documentation.
+
+
 Workflow Summary
 ----------------
 
 1. **Feature Development**: All new features and bug fixes are developed in separate branches off of ``development``.
 2. **Testing and Integration**: When a feature is complete, it is merged into ``development`` for testing and integration with other recent changes.
 3. **Stable Release Preparation**: Once the ``development`` branch is stable and ready for release, it is merged into ``main``, creating an official, stable release.
 4. **Major Version Development**: Experimental or significant changes go into ``dev-3.0.0`` until they are ready for production.
+5. **Documentation Deployment**: Updates to the ``docs-dev`` directory are built and deployed to the ``gh-pages`` branch automatically by GitHub Actions.
+
 
 Branching Best Practices
 -------------------------
 
-- **Keep ``main`` stable**: Only tested, production-ready code should be merged into ``main``.
+- **Keep main stable**: Only tested, production-ready code should be merged into ``main``.
 - **Use Feature Branches**: For each new feature or fix, create a branch off ``development``. This keeps ``development`` organized and easier to manage.
 - **Document and Review Changes**: Always document significant changes to the codebase. Use pull requests to review and approve changes before merging into shared branches.
+- **Do Not Modify ``gh-pages`` Directly**: Always update documentation in the ``docs-dev`` directory in the ``development`` branch.
+
 
 Conclusion
 ----------

docs-dev/usage-of-coverage.rst → docs-dev/guider-of-coverage.rst

@@ -1,25 +1,31 @@
 Coverage Guide
 ==============
 
-To measure test coverage in the Biofilter project, we use `Coverage.py`. This guide outlines the steps to install and run `coverage` and generate reports.
+To measure test coverage in the Biofilter project, we use `Coverage.py`. This guide outlines the steps to install, run, and generate coverage reports while considering the integration with Poetry and the CI/CD pipeline.
 
 1. Install Coverage.py
 -----------------------
 
-Install `coverage` via pip:
+`Coverage.py` is already included in the project's development dependencies via Poetry. To ensure it is installed, simply run:
 
 .. code-block:: bash
 
-   pip install coverage
+   poetry install
+
+This command installs all development dependencies, including `Coverage.py`.
+
+.. note::
+
+   There is no need to install `coverage` manually using `pip`, as it is managed through Poetry.
 
 2. Run Tests with Coverage
 --------------------------
 
-In the Biofilter project directory, use `coverage` to run the tests and collect coverage data:
+In the Biofilter project directory, use `coverage` to run the tests and collect coverage data. Since we are using Poetry, the command is:
 
 .. code-block:: bash
 
-   coverage run -m pytest
+   poetry run coverage run -m pytest
 
 This command uses `coverage` to execute `pytest`, running all tests and collecting information on which parts of the code are covered.
 
@@ -30,7 +36,7 @@ After running the tests, generate a coverage report in the terminal:
 
 .. code-block:: bash
 
-   coverage report -m
+   poetry run coverage report -m
 
 - The ``-m`` option displays which lines were not covered.
 
@@ -41,7 +47,7 @@ For a more detailed view, generate an HTML report:
 
 .. code-block:: bash
 
-   coverage html
+   poetry run coverage html
 
 This creates a directory called ``htmlcov`` with an ``index.html`` file. Open this file in a browser for a detailed view of the coverage.
 
@@ -65,31 +71,40 @@ To exclude specific files or certain lines (e.g., docstrings or debugging instru
 
 This configuration ensures that coverage focuses only on the relevant parts of the codebase.
 
+Integration with CI/CD
+----------------------
+
+Test coverage is also verified automatically in the CI/CD pipeline through GitHub Actions. This ensures that every change to the codebase maintains or improves test coverage. Before pushing changes, it is recommended to check the coverage locally using the commands outlined above.
+
+.. important::
+
+   Always verify coverage locally before committing to avoid failures during the CI/CD process.
+
 Summary of Commands
 -------------------
 
-1. **Install**: 
+1. **Install dependencies**: (if not already installed) 
 
    .. code-block:: bash
 
-      pip install coverage
+      poetry install
 
 2. **Run tests with coverage**: 
 
    .. code-block:: bash
 
-      coverage run -m pytest
+      poetry run coverage run -m pytest
 
 3. **Generate terminal report**: 
 
    .. code-block:: bash
 
-      coverage report -m
+      poetry run coverage report -m
 
 4. **Generate HTML report**: 
 
    .. code-block:: bash
 
-      coverage html
+      poetry run coverage html
+
 
-These steps will help you measure test coverage in the Biofilter project using `Coverage.py`.