From ca333e99fc80eb3917dbe77b454facf1dbf1fceb Mon Sep 17 00:00:00 2001 From: Arseniy Obolenskiy Date: Sat, 25 Jan 2025 16:53:33 +0100 Subject: [PATCH 1/2] Add CI graph to the documentation --- docs/_static/.gitkeep | 0 docs/_static/ci_graph.svg | 252 ++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/user_guide/ci.rst | 15 +++ scripts/jobs_graph.py | 43 +++++++ 5 files changed, 311 insertions(+) delete mode 100644 docs/_static/.gitkeep create mode 100644 docs/_static/ci_graph.svg create mode 100644 docs/user_guide/ci.rst create mode 100644 scripts/jobs_graph.py diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/_static/ci_graph.svg b/docs/_static/ci_graph.svg new file mode 100644 index 000000000..3810ae127 --- /dev/null +++ b/docs/_static/ci_graph.svg @@ -0,0 +1,252 @@ + + + + + + + + + +clang-format + +clang-format + + + +ubuntu-gcc-build + +ubuntu-gcc-build + + + +clang-format->ubuntu-gcc-build + + + + + +ubuntu-clang-build + +ubuntu-clang-build + + + +clang-format->ubuntu-clang-build + + + + + +macos-clang-build + +macos-clang-build + + + +clang-format->macos-clang-build + + + + + +windows-msvc-build + +windows-msvc-build + + + +clang-format->windows-msvc-build + + + + + +windows-clang-build + +windows-clang-build + + + +clang-format->windows-clang-build + + + + + +python-lint + +python-lint + + + +python-lint->ubuntu-gcc-build + + + + + +python-lint->ubuntu-clang-build + + + + + +python-lint->macos-clang-build + + + + + +python-lint->windows-msvc-build + + + + + +python-lint->windows-clang-build + + + + + +ubuntu-gcc-build-extended + +ubuntu-gcc-build-extended + + + +ubuntu-gcc-build->ubuntu-gcc-build-extended + + + + + +ubuntu-gcc-build-codecov + +ubuntu-gcc-build-codecov + + + +ubuntu-gcc-build-extended->ubuntu-gcc-build-codecov + + + + + +ubuntu-clang-build-extended + +ubuntu-clang-build-extended + + + +ubuntu-clang-build->ubuntu-clang-build-extended + + + + + +ubuntu-clang-sanitizer-build + +ubuntu-clang-sanitizer-build + + + +ubuntu-clang-build->ubuntu-clang-sanitizer-build + + + + + +ubuntu-clang-build-extended->ubuntu-gcc-build-codecov + + + + + +ubuntu-clang-sanitizer-build-extended + +ubuntu-clang-sanitizer-build-extended + + + +ubuntu-clang-sanitizer-build->ubuntu-clang-sanitizer-build-extended + + + + + +ubuntu-gcc-build-perf-stats + +ubuntu-gcc-build-perf-stats + + + +ubuntu-clang-sanitizer-build-extended->ubuntu-gcc-build-perf-stats + + + + + +macos-clang-build-extended + +macos-clang-build-extended + + + +macos-clang-build->macos-clang-build-extended + + + + + +macos-clang-build-extended->ubuntu-gcc-build-codecov + + + + + +windows-msvc-build-extended + +windows-msvc-build-extended + + + +windows-msvc-build->windows-msvc-build-extended + + + + + +windows-msvc-build-extended->ubuntu-gcc-build-perf-stats + + + + + +windows-clang-build-extended + +windows-clang-build-extended + + + +windows-clang-build->windows-clang-build-extended + + + + + +windows-clang-build-extended->ubuntu-gcc-build-perf-stats + + + + + +ubuntu-gcc-build-codecov->ubuntu-gcc-build-perf-stats + + + + + diff --git a/docs/index.rst b/docs/index.rst index 603e91093..b79ec282a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,3 +11,4 @@ Below is the table of contents for the Parallel Programming Course documentation user_guide/download user_guide/environment user_guide/submit_work + user_guide/ci diff --git a/docs/user_guide/ci.rst b/docs/user_guide/ci.rst new file mode 100644 index 000000000..7feba2074 --- /dev/null +++ b/docs/user_guide/ci.rst @@ -0,0 +1,15 @@ +Continuous Integration (CI) +============================ + +Students need to pass all the checks in the CI pipeline before their work can be considered for submission. +This includes successful code checkout, build ans testing stages. +Each integration is verified by an automated build and automated tests. + +CI Pipeline +------------ + +The CI pipeline for this project is illustrated in the following diagram: + +.. image:: ../_static/ci_graph.svg + :alt: CI Pipeline Diagram + :align: center diff --git a/scripts/jobs_graph.py b/scripts/jobs_graph.py new file mode 100644 index 000000000..51205ce34 --- /dev/null +++ b/scripts/jobs_graph.py @@ -0,0 +1,43 @@ +import os + +try: + import yaml +except ImportError: + print("Please install pyyaml: pip install pyyaml") + exit(1) + +try: + import graphviz +except ImportError: + print("Please install graphviz: pip install graphviz") + exit(1) + + +def parse_gha_yml(file_path): + with open(file_path, "r") as file: + gha_data = yaml.safe_load(file) + return gha_data + +def build_jobs_graph(gha_data): + jobs = gha_data.get("jobs", {}) + dot = graphviz.Digraph() + + for job_name, job_data in jobs.items(): + dot.node(job_name) + needs = job_data.get("needs", []) + if isinstance(needs, str): + needs = [needs] + for dependency in needs: + dot.edge(dependency, job_name) + + return dot + +def save_graph(dot, filename, file_format): + dot.render(filename, format=file_format, cleanup=True) + +if __name__ == "__main__": + gha_file_path = os.path.join(".github", "workflows", "main.yml") + svg_path = os.path.join("docs", "_static", "ci_graph") + gha_data = parse_gha_yml(gha_file_path) + jobs_graph = build_jobs_graph(gha_data) + save_graph(jobs_graph, svg_path, "svg") From b7aec4136c2ab16edf4b3b464d4d4e19b4ea1e4a Mon Sep 17 00:00:00 2001 From: Arseniy Obolenskiy Date: Sat, 25 Jan 2025 17:07:16 +0100 Subject: [PATCH 2/2] Add CI description page --- docs/Makefile | 2 + docs/locale/en/LC_MESSAGES/user_guide/ci.po | 46 ++++++++++++++++++++ docs/locale/ru/LC_MESSAGES/user_guide/ci.po | 47 +++++++++++++++++++++ scripts/jobs_graph.py | 3 ++ 4 files changed, 98 insertions(+) create mode 100644 docs/locale/en/LC_MESSAGES/user_guide/ci.po create mode 100644 docs/locale/ru/LC_MESSAGES/user_guide/ci.po diff --git a/docs/Makefile b/docs/Makefile index 7b9fbfc34..6915abb7d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -5,6 +5,7 @@ # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build +SPHINXINTL ?= sphinx-intl SOURCEDIR = . BUILDDIR = _build/html SPHINXOPTS += -W --keep-going -n @@ -18,5 +19,6 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile + @$(SPHINXINTL) update -p _build/gettext -l en -l ru @$(SPHINXBUILD) -b html -D language=en "$(SOURCEDIR)" "$(BUILDDIR)/en" $(SPHINXOPTS) $(O) @$(SPHINXBUILD) -b html -D language=ru "$(SOURCEDIR)" "$(BUILDDIR)/ru" $(SPHINXOPTS) $(O) diff --git a/docs/locale/en/LC_MESSAGES/user_guide/ci.po b/docs/locale/en/LC_MESSAGES/user_guide/ci.po new file mode 100644 index 000000000..bfe366939 --- /dev/null +++ b/docs/locale/en/LC_MESSAGES/user_guide/ci.po @@ -0,0 +1,46 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, Learning Process +# This file is distributed under the same license as the Parallel +# Programming Course package. +# FIRST AUTHOR , 2025. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Parallel Programming Course \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-01-25 16:54+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: en\n" +"Language-Team: en \n" +"Plural-Forms: nplurals=2; plural=(n != 1);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.16.0\n" + +#: ../../user_guide/ci.rst:2 +msgid "Continuous Integration (CI)" +msgstr "" + +#: ../../user_guide/ci.rst:4 +msgid "" +"Students need to pass all the checks in the CI pipeline before their work" +" can be considered for submission. This includes successful code " +"checkout, build ans testing stages. Each integration is verified by an " +"automated build and automated tests." +msgstr "" + +#: ../../user_guide/ci.rst:9 +msgid "CI Pipeline" +msgstr "" + +#: ../../user_guide/ci.rst:11 +msgid "The CI pipeline for this project is illustrated in the following diagram:" +msgstr "" + +#: ../../user_guide/ci.rst:13 +msgid "CI Pipeline Diagram" +msgstr "" + diff --git a/docs/locale/ru/LC_MESSAGES/user_guide/ci.po b/docs/locale/ru/LC_MESSAGES/user_guide/ci.po new file mode 100644 index 000000000..a7f4c7b8a --- /dev/null +++ b/docs/locale/ru/LC_MESSAGES/user_guide/ci.po @@ -0,0 +1,47 @@ +# SOME DESCRIPTIVE TITLE. +# Copyright (C) 2025, Learning Process +# This file is distributed under the same license as the Parallel +# Programming Course package. +# FIRST AUTHOR , 2025. +# +#, fuzzy +msgid "" +msgstr "" +"Project-Id-Version: Parallel Programming Course \n" +"Report-Msgid-Bugs-To: \n" +"POT-Creation-Date: 2025-01-25 16:54+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language: ru\n" +"Language-Team: ru \n" +"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2);\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 2.16.0\n" + +#: ../../user_guide/ci.rst:2 +msgid "Continuous Integration (CI)" +msgstr "" + +#: ../../user_guide/ci.rst:4 +msgid "" +"Students need to pass all the checks in the CI pipeline before their work" +" can be considered for submission. This includes successful code " +"checkout, build ans testing stages. Each integration is verified by an " +"automated build and automated tests." +msgstr "" + +#: ../../user_guide/ci.rst:9 +msgid "CI Pipeline" +msgstr "" + +#: ../../user_guide/ci.rst:11 +msgid "The CI pipeline for this project is illustrated in the following diagram:" +msgstr "" + +#: ../../user_guide/ci.rst:13 +msgid "CI Pipeline Diagram" +msgstr "" + diff --git a/scripts/jobs_graph.py b/scripts/jobs_graph.py index 51205ce34..52824d22c 100644 --- a/scripts/jobs_graph.py +++ b/scripts/jobs_graph.py @@ -18,6 +18,7 @@ def parse_gha_yml(file_path): gha_data = yaml.safe_load(file) return gha_data + def build_jobs_graph(gha_data): jobs = gha_data.get("jobs", {}) dot = graphviz.Digraph() @@ -32,9 +33,11 @@ def build_jobs_graph(gha_data): return dot + def save_graph(dot, filename, file_format): dot.render(filename, format=file_format, cleanup=True) + if __name__ == "__main__": gha_file_path = os.path.join(".github", "workflows", "main.yml") svg_path = os.path.join("docs", "_static", "ci_graph")