diff --git a/README.md b/README.md index 95c81ce..c063702 100644 --- a/README.md +++ b/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 diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 0000000..d804b8a --- /dev/null +++ b/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 `_ 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. diff --git a/docs/generate_diagrams.py b/docs/generate_diagrams.py new file mode 100644 index 0000000..675f812 --- /dev/null +++ b/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 diff --git a/docs/images/contributing.png b/docs/images/contributing.png new file mode 100644 index 0000000..9fb1a13 Binary files /dev/null and b/docs/images/contributing.png differ diff --git a/docs/images/development_cycle.png b/docs/images/development_cycle.png new file mode 100644 index 0000000..7850e3e Binary files /dev/null and b/docs/images/development_cycle.png differ diff --git a/docs/index.rst b/docs/index.rst index 0dac009..8791ab5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -73,5 +73,6 @@ it and it's options. :hidden: example.rst + contributing.rst changelog.rst modules/modules.rst diff --git a/poetry.lock b/poetry.lock index 8cb4a86..5edecb9 100644 --- a/poetry.lock +++ b/poetry.lock @@ -284,6 +284,22 @@ tomli = {version = "*", optional = true, markers = "python_full_version <= \"3.1 [package.extras] toml = ["tomli"] +[[package]] +name = "diagrams" +version = "0.23.1" +description = "Diagram as Code" +category = "dev" +optional = false +python-versions = ">=3.6,<4.0" +files = [ + {file = "diagrams-0.23.1-py3-none-any.whl", hash = "sha256:64558979974a8a12aefbb8757c9118120b942c0e2a6c37862a250887eed301f1"}, + {file = "diagrams-0.23.1.tar.gz", hash = "sha256:56230633ee70106ecea38b82dc447084a114055feddda6dc18d1faa1b96f0049"}, +] + +[package.dependencies] +graphviz = ">=0.13.2,<0.20.0" +jinja2 = ">=2.10,<4.0" + [[package]] name = "dill" version = "0.3.5.1" @@ -504,6 +520,23 @@ files = [ gitdb = ">=4.0.1,<5" typing-extensions = {version = ">=3.7.4.3", markers = "python_version < \"3.8\""} +[[package]] +name = "graphviz" +version = "0.19.2" +description = "Simple Python interface for Graphviz" +category = "dev" +optional = false +python-versions = ">=3.7" +files = [ + {file = "graphviz-0.19.2-py3-none-any.whl", hash = "sha256:c0a6ac9fadaa308c4ab0d526749c6e127425ec5a76644bbb03e2e04b19a9da9f"}, + {file = "graphviz-0.19.2.zip", hash = "sha256:7c90cebc147c18bcdffcd3c76db58cbface5d45fe0247a2f3bfb144d32a8c77c"}, +] + +[package.extras] +dev = ["flake8", "pep8-naming", "tox (>=3)", "twine", "wheel"] +docs = ["sphinx (>=1.8)", "sphinx-autodoc-typehints", "sphinx-rtd-theme"] +test = ["coverage", "mock (>=4)", "pytest (>=6)", "pytest-cov", "pytest-mock (>=3)"] + [[package]] name = "identify" version = "2.5.5" @@ -1809,4 +1842,4 @@ testing = ["func-timeout", "jaraco.itertools", "pytest (>=6)", "pytest-black (>= [metadata] lock-version = "2.0" python-versions = "^3.7" -content-hash = "8a8342720b32c1ef7740bdefe47ae88f7cacfa14cd840eebb2899abf3eaf3824" +content-hash = "d03a2beca69866dd7c70c920526bebd0075a427379e2c74039698dfa91d6dac3" diff --git a/pyproject.toml b/pyproject.toml index 3ec0d86..d020e52 100644 --- a/pyproject.toml +++ b/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"