Feat/add diagrams to docs

README.md

@@ -179,13 +179,18 @@ safety check --file requirements/dev.txt --full-report
 
 ### Documentation
 
-To check Python documentation generation, run
+To generate the project's documentation diagrams, run
+```
+(cd docs/images && python ../generate_diagrams.py)
+```
+
+To check the project's documentation generation, run
 ```
 sphinx-apidoc --module-first --private --output-dir docs/modules cly
 sphinx-build -W -T -v -n -a docs public
 ```
 
-To generate Python documentation, run
+To generate the project's documentation, run
 ```
 sphinx-apidoc --module-first --private --output-dir docs/modules cly
 sphinx-build -v -n -a docs public

docs/contributing.rst

@@ -0,0 +1,78 @@
+Contributing
+============
+
+Here, you can find out how (**and why**) the project is structured to best
+understand it and be able to help us improve the project even further.
+
+The following diagram shows the steps for contributing to the project.
+
+.. image:: images/contributing.png
+
+The dashed arrow for creating a fork is proposal. Only by creating an issue, you
+are already helping this project improve! But if you want to further help and fix
+issues yourself, follow the Development Cycle section.
+
+Development Cycle
+-----------------
+
+The following diagram shows the steps for contributing to the project.
+
+.. image:: images/development_cycle.png
+
+TALK ABOUT THE PREVIOUS STEPS
+
+1 create fork
+
+2 create branch WITH GOOD NAME (SECTION ABOUT THIS)
+
+3 create PR (link to quality and CI section)
+
+4 maintainers will review and merge the PR (link to versioning and CD section)
+
+AFTER 1 AND 2
+
+choose the development environment you want to use
+
+write/refactor the code to address the issue being worked on
+
+run the quality checks
+
+run git commands
+
+add
+
+commit (at this time, pre-commit will run, if it was set up)
+
+push (if the PR was already open, this will trigger the CI to run again)
+
+BEFORE 3 AND 4
+
+Versioning
+----------
+
+The project follows the `Semantic Versioning <https://semver.org/>`_ to assign
+and increment the project version. This is enforced through the following:
+
+- **Tests**: the tests in ``tests/test_version.py`` file enforces the correct use of
+  Semantic Versioning (which are reproduced) by the CI pipeline of the project.
+- **Automation**:
+
+  - **tagging and releasing**: through the ``scripts/versioning.py`` which collects
+    the necessary information to the CD pipeline of the project. For this, a
+    pull request only changing the project version (and the releases notes, if
+    necessary), must be opened and closed.
+  - **update of release notes**: through the pull request title, the CD pipeline
+    of the project updates the releases notes in the documentation after each
+    pull request is closed. It is **very important to write good pull request
+    titles** because of this.
+
+  The automation options are mutually exclusive, i.e. only one of them is
+  triggered by the CD pipeline at a time.
+
+For the first release, the entire versioning pipeline file,
+``.github/workflows/versioning.yml``, must be uncommented during the tagging and
+releasing pull request, along with the ``on.push.paths`` both in
+``.github/workflows/ci.yml`` and ``.github/workflows/cd.yml`` files, and
+``Check version information`` step in ``project-check.steps`` in
+``.github/workflows/ci.yml`` file. Also, a Personal Access Token named
+**ACTIONS_TOKEN** must be added to Actions secrets, in the repository settings.

docs/generate_diagrams.py

@@ -0,0 +1,50 @@
+from diagrams import Diagram, Edge, Cluster, Node
+from diagrams.onprem.vcs import Git, Github
+from diagrams.onprem.ci import GithubActions
+from diagrams.onprem.container import Docker
+# diagrams.programming.language.Bash
+from diagrams.programming.language import Python
+from diagrams.programming.flowchart import Action
+from diagrams.c4 import Person, Container
+
+graph_attr = {
+    "bgcolor": "transparent",
+    "fontsize": "50",
+}
+node_attr = {
+    "fontsize": "20",
+}
+edge_attr = {
+    "fontsize": "50",
+}
+
+with Diagram("Contributing", show=False, graph_attr=graph_attr):
+    # fork = Github("Create fork")
+
+    # # with Cluster("Issue"):
+    # Node("Search issue") - Node("Create new issue") >> fork
+
+    # fork >> Git("Create branch") >> Edge(label="Development Cycle") >> Git("userdb")
+
+    fork = Github("Create fork")
+
+    issue = Container("Issue", description="Search or create new issue")
+    issue >> Edge(style="dashed") >> fork
+
+    main = fork >> Git("Create branch") >> Edge(label="Development Cycle") >> Github("Create PR")
+    main >> GithubActions("CI Pipeline")
+    main >> Github("Merge PR") >> GithubActions("CD Pipeline")
+
+with Diagram("Development Cycle", show=False, graph_attr=graph_attr):
+    with Cluster("Development environment"):
+        dev_env = [
+            Docker("Container image"),
+            Python("Poetry"),
+            Python("Pure Python"),
+        ]
+
+    commit = Git("Commit")
+    push = Git("Push")
+    coding = Container("Coding", description="Implement feature, fix bug, etc.")
+    commit << Edge(style="dashed") << Container("pre-commit")
+    dev_env >> coding >> Container("Quality check") >> Git("Add") >> commit >> push >> Edge(style="dashed") >> coding

docs/index.rst

@@ -73,5 +73,6 @@ it and it's options.
    :hidden:
 
    example.rst
+   contributing.rst
    changelog.rst
    modules/modules.rst

pyproject.toml

@@ -26,6 +26,9 @@ sphinx-rtd-theme = "^1.0.0"
 toml = "^0.10.2"
 types-toml = "^0.10.8"
 
+[tool.poetry.group.docs.dependencies]
+diagrams = "^0.23.1"
+
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"