From 8d2c8bff0178806e1102cde03eae9ea004fc783c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Tue, 23 Apr 2024 13:40:34 +0200 Subject: [PATCH 01/21] docs: Create an empty mkdoc website --- docs/website/docs/index.md | 3 +++ docs/website/mkdocs.yml | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 38 insertions(+) create mode 100644 docs/website/docs/index.md create mode 100644 docs/website/mkdocs.yml diff --git a/docs/website/docs/index.md b/docs/website/docs/index.md new file mode 100644 index 0000000..ceea72a --- /dev/null +++ b/docs/website/docs/index.md @@ -0,0 +1,3 @@ +# Home + +The OpenSavvy Playground is a project template with pre-configured CI/CD, documentation generator, etc. diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml new file mode 100644 index 0000000..e2cc761 --- /dev/null +++ b/docs/website/mkdocs.yml @@ -0,0 +1,35 @@ +site_name: OpenSavvy Playground +site_author: OpenSavvy & contributors +site_description: > + Project template with CI/CD and IDE configuration. + +theme: + name: material + features: + - announce.dismiss + - content.action.edit + - content.action.view + - content.code.annotate + - content.code.copy + # - content.code.select + # - content.footnote.tooltips + # - content.tabs.link + - content.tooltips + # - header.autohide + # - navigation.expand + - navigation.footer + - navigation.indexes + # - navigation.instant + # - navigation.instant.prefetch + # - navigation.instant.progress + # - navigation.prune + - navigation.sections + - navigation.tabs + # - navigation.tabs.sticky + - navigation.top + - navigation.tracking + - search.highlight + - search.share + - search.suggest + - toc.follow + # - toc.integrate -- 2.51.2 From 3ef515826992398e09a5318540b084b3357f7399 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Tue, 23 Apr 2024 13:54:34 +0200 Subject: [PATCH 02/21] ci(gitlab): Generate the documentation website --- .gitlab-ci.yml | 2 ++ docs/website/.gitlab-ci.yml | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 docs/website/.gitlab-ci.yml diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index f132dfd..afab986 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -8,6 +8,8 @@ include: - remote: https://gitlab.com/opensavvy/ci-templates/-/raw/main/version.gitlab-ci.yml - remote: https://gitlab.com/opensavvy/ci-templates/-/raw/main/mirror.gitlab-ci.yml + - local: docs/website/.gitlab-ci.yml + variables: # https://gitlab.com/opensavvy/automation/containers ci_containers: 0.3.0 diff --git a/docs/website/.gitlab-ci.yml b/docs/website/.gitlab-ci.yml new file mode 100644 index 0000000..7774f43 --- /dev/null +++ b/docs/website/.gitlab-ci.yml @@ -0,0 +1,18 @@ + +mkdocs: + image: + name: squidfunk/mkdocs-material + entrypoint: [ "/bin/sh", "-c" ] + stage: build + + before_script: + - cd docs/website + - ls + + script: + - pwd + - mkdocs build --site-dir ../../docs-website + + artifacts: + paths: + - docs-website -- 2.51.2 From ea79ba03a616820fb61bcf3e2e2b0139fd2243d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Tue, 23 Apr 2024 14:46:25 +0200 Subject: [PATCH 03/21] ci(gitlab): Script to generate the review app URL for a job's artifacts --- .gitlab/ci/review-url.sh | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100755 .gitlab/ci/review-url.sh diff --git a/.gitlab/ci/review-url.sh b/.gitlab/ci/review-url.sh new file mode 100755 index 0000000..b52fe4d --- /dev/null +++ b/.gitlab/ci/review-url.sh @@ -0,0 +1,19 @@ +#!/usr/bin/env sh + +################################################################################ +# +# Generates the review app URL for a given CI job. +# +# +# Usage: +# .gitlab/ci/review-url.sh ARTIFACT_PATH +# +################################################################################ + +# Yes, there are no predefined variables for this, +# so we use a ugly rewrite. +# https://gitlab.com/gitlab-org/gitlab/-/issues/450912 + +root=$(echo "$CI_PAGES_URL" | sed 's // XSTARTX ;s / /-/ ;s XSTARTX // ') + +echo "$root/-/jobs/$CI_JOB_ID/artifacts/$1" -- 2.51.2 From 2255d2d0633c19bc4b6cb7905b75ea7c5283d16a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Tue, 23 Apr 2024 14:46:46 +0200 Subject: [PATCH 04/21] ci(gitlab): Enable review apps for the mkdocs site --- docs/website/.gitlab-ci.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/website/.gitlab-ci.yml b/docs/website/.gitlab-ci.yml index 7774f43..6934a77 100644 --- a/docs/website/.gitlab-ci.yml +++ b/docs/website/.gitlab-ci.yml @@ -13,6 +13,16 @@ mkdocs: - pwd - mkdocs build --site-dir ../../docs-website + after_script: + - echo "URL=$(.gitlab/ci/review-url.sh docs-website/index.html)" >>docs.env + artifacts: paths: - docs-website + reports: + dotenv: docs.env + + environment: + name: review/$CI_COMMIT_REF_SLUG/docs + url: $URL + deployment_tier: development -- 2.51.2 From efdaad6d2f80153a5ffa7e4af99632d7ffdb8098 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Tue, 23 Apr 2024 14:51:02 +0200 Subject: [PATCH 05/21] ci(gitlab): Add region markers to the Playground mirroring logic --- .gitlab-ci.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index afab986..77c3965 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -27,6 +27,8 @@ hello-world: - echo 'Hello world' interruptible: true +# region Automatically mirror the previous layer of the playground + mirror-playground: stage: deploy extends: [ .os.mirror ] @@ -46,3 +48,5 @@ mirror-playground: - if: $CI_PIPELINE_SOURCE == 'schedule' - when: manual allow_failure: true + +# endregion -- 2.51.2 From ac879fe79a08875ba4c3e37e2fc4779a4f912e42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Tue, 23 Apr 2024 14:52:57 +0200 Subject: [PATCH 06/21] ci(gitlab): Publish the mkdocs website to GitLab Pages --- .gitlab-ci.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 77c3965..58358b7 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -50,3 +50,25 @@ mirror-playground: allow_failure: true # endregion +# region GitLab Pages + +pages: + image: alpine:latest + stage: deploy + needs: + - job: mkdocs + artifacts: true + + script: + - mkdir -p public + - mv docs-website public/docs + + artifacts: + paths: + - public + + rules: + - if: $CI_COMMIT_TAG + interruptible: false + +# endregion -- 2.51.2 From bcfb251dfdc89cb12a05fee4e84149c1311016b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Tue, 23 Apr 2024 14:56:29 +0200 Subject: [PATCH 07/21] upgrade: OpenSavvy CI Containers 0.4.1 --- .gitlab-ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index f132dfd..4acf521 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -10,7 +10,7 @@ include: variables: # https://gitlab.com/opensavvy/automation/containers - ci_containers: 0.3.0 + ci_containers: 0.4.1 workflow: rules: -- 2.51.2 From e2190a000509f06f680788519ba6b35f10a92049 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Tue, 23 Apr 2024 15:11:15 +0200 Subject: [PATCH 08/21] ci(gitlab): Link the mkdocs site to the GitLab repository --- docs/website/.gitlab-ci.yml | 2 ++ docs/website/mkdocs.yml | 5 +++++ 2 files changed, 7 insertions(+) diff --git a/docs/website/.gitlab-ci.yml b/docs/website/.gitlab-ci.yml index 6934a77..cbe109a 100644 --- a/docs/website/.gitlab-ci.yml +++ b/docs/website/.gitlab-ci.yml @@ -8,6 +8,8 @@ mkdocs: before_script: - cd docs/website - ls + - 'echo "repo_url: $CI_PROJECT_URL">>mkdocs.yml' + - 'echo "repo_name: $CI_PROJECT_TITLE">>mkdocs.yml' script: - pwd diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index e2cc761..787b9ef 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -33,3 +33,8 @@ theme: - search.suggest - toc.follow # - toc.integrate + icon: + edit: material/pencil + view: material/eye + +edit_uri: edit/main/docs/website -- 2.51.2 From 5d30cd88903e99c0d164ae949d603510e0918368 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Tue, 23 Apr 2024 23:40:39 +0200 Subject: [PATCH 09/21] upgrade: Gradle 8.7 --- gradle/wrapper/gradle-wrapper.properties | 2 +- gradlew.bat | 20 ++++++++++---------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index a80b22c..b82aa23 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,6 +1,6 @@ distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip networkTimeout=10000 validateDistributionUrl=true zipStoreBase=GRADLE_USER_HOME diff --git a/gradlew.bat b/gradlew.bat index 93e3f59..25da30d 100644 --- a/gradlew.bat +++ b/gradlew.bat @@ -43,11 +43,11 @@ set JAVA_EXE=java.exe %JAVA_EXE% -version >NUL 2>&1 if %ERRORLEVEL% equ 0 goto execute -echo. -echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. -echo. -echo Please set the JAVA_HOME variable in your environment to match the -echo location of your Java installation. +echo. 1>&2 +echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2 +echo. 1>&2 +echo Please set the JAVA_HOME variable in your environment to match the 1>&2 +echo location of your Java installation. 1>&2 goto fail @@ -57,11 +57,11 @@ set JAVA_EXE=%JAVA_HOME%/bin/java.exe if exist "%JAVA_EXE%" goto execute -echo. -echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% -echo. -echo Please set the JAVA_HOME variable in your environment to match the -echo location of your Java installation. +echo. 1>&2 +echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2 +echo. 1>&2 +echo Please set the JAVA_HOME variable in your environment to match the 1>&2 +echo location of your Java installation. 1>&2 goto fail -- 2.51.2 From dcb3ed00a053c5a36fa5680a59ec729eae3ca245 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Tue, 23 Apr 2024 23:42:13 +0200 Subject: [PATCH 10/21] upgrade: OpenSavvy Gradle Conventions 1.2.1 See https://gitlab.com/opensavvy/automation/gradle-conventions/-/releases/1.2.1 --- gradle/conventions/settings.gradle.kts | 2 +- settings.gradle.kts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/gradle/conventions/settings.gradle.kts b/gradle/conventions/settings.gradle.kts index f546984..e57f7e9 100644 --- a/gradle/conventions/settings.gradle.kts +++ b/gradle/conventions/settings.gradle.kts @@ -43,7 +43,7 @@ pluginManagement { } plugins { - id("dev.opensavvy.conventions.settings") version "1.2.0" + id("dev.opensavvy.conventions.settings") version "1.2.1" } enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS") diff --git a/settings.gradle.kts b/settings.gradle.kts index 48dac6b..ec06313 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -47,7 +47,7 @@ pluginManagement { } plugins { - id("dev.opensavvy.conventions.settings") version "1.2.0" + id("dev.opensavvy.conventions.settings") version "1.2.1" } include( -- 2.51.2 From 6667212647cdab3871170bbe4a8184362e00ee8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 25 Apr 2024 14:55:05 +0200 Subject: [PATCH 11/21] upgrade: OpenSavvy Gradle Conventions 1.3.0 See https://gitlab.com/opensavvy/automation/gradle-conventions/-/releases/1.3.0 --- gradle/conventions/settings.gradle.kts | 2 +- settings.gradle.kts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/gradle/conventions/settings.gradle.kts b/gradle/conventions/settings.gradle.kts index e57f7e9..dc97e54 100644 --- a/gradle/conventions/settings.gradle.kts +++ b/gradle/conventions/settings.gradle.kts @@ -43,7 +43,7 @@ pluginManagement { } plugins { - id("dev.opensavvy.conventions.settings") version "1.2.1" + id("dev.opensavvy.conventions.settings") version "1.3.0" } enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS") diff --git a/settings.gradle.kts b/settings.gradle.kts index ec06313..c6dea82 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -47,7 +47,7 @@ pluginManagement { } plugins { - id("dev.opensavvy.conventions.settings") version "1.2.1" + id("dev.opensavvy.conventions.settings") version "1.3.0" } include( -- 2.51.2 From 8abc5501857cd6e8aa1e75952ccb050ade59c4f3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= Date: Thu, 25 Apr 2024 19:29:17 +0200 Subject: [PATCH 12/21] docs: Create the design decision repository --- docs/design/README.md | 105 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/design/README.md diff --git a/docs/design/README.md b/docs/design/README.md new file mode 100644 index 0000000..5da2acb --- /dev/null +++ b/docs/design/README.md @@ -0,0 +1,105 @@ +# Design decisions + +When we create software, we often have to decide between multiple ways to realize our vision. When maintaining a project, we may think of a "better" way to do things. At this point, we must be able to quickly decide whether: +- The new idea was one of the considered options but was discarded for some reason, +- The new idea was not considered, but some constraint makes it an incorrect solution, +- The new idea was not considered, and it is indeed better than the implemented solution. + +Deciding between these situations can be very hard when no context is available, especially in teams which make decisions during meetings, which leave no trail. There are multiple ways to increase available context for future decisions: writing more comprehensive documentation comments, adding details in the Git history, and writing detailed documents describing the decisions. + +This directory implements the latter pattern, also called Architecture Decision Records ([learn more](https://adr.github.io/)). Each document describes a single decision and considered alternatives. + +[TOC] + +## Which decisions should be recorded? + +Whenever there is a chance that multiple solutions fit a problem, or when the plan has to change because the originally-imagined solution turned out to be unfitting. As a rule of thumb, if a reviewer asks you why you did something one way instead of another, it's probably worth recording this decision. + +However, not all decisions are worth adding to this directory: +- If a decision is specifically localized to one file (e.g. to one function, to one class), a regular comment at that place is more useful because it is better co-located. +- If a decision is a one-time thing and has no consequences for the future, describing it in the commit description (or merge request description) is more efficient. For example, putting in place a new workflow, which has its own documentation file in the repository, doesn't require a record, as it would otherwise mostly be a duplicate of the chosen workflow. + +These kinds of decisions likely require a new record: +- Deciding between two alternative ways to do things that are very similar. +- Decisions that affect more than one file (e.g. an entire package, an entire module, the entire project…). +- Decisions that have consequences on the future (e.g. future maintainers should continue following them to keep coherence). + +## Creating a new record + +Here is a template for new records: +```markdown +# + +| | | +|---------------|----------| +| Status | <Status> | +| Discussion | <Link> | +| Superseded by | <link·s> | +| Relates to | <Link·s> | + +<Short description> + +[TOC] + +## The problem + +## Constraints + +## Considered solutions + +## Selected solution +``` + +The following describes all the fields of the template and what they should be filled in with. + +**Status:** + +[![Status: draft](https://badgen.net/static/Status/draft/purple)](https://gitlab.com/opensavvy/playgrounds/baseline/-/blob/main/docs/design/README.md#creating-a-new-record) • This decision is a draft. It should not yet be followed. The field "Discussion" should be present. + +[![Status: active](https://badgen.net/static/Status/active/purple)](https://gitlab.com/opensavvy/playgrounds/baseline/-/blob/main/docs/design/README.md#creating-a-new-record) • This decision is active and should be followed in all new code. When editing existing code which doesn't follow this decision, consider rewriting it so it does. + +[![Status: archived](https://badgen.net/static/Status/archived/purple)](https://gitlab.com/opensavvy/playgrounds/baseline/-/blob/main/docs/design/README.md#creating-a-new-record) • This decision was active, but isn't anymore. New code isn't required to follow it. Existing code may or may not still follow it, and no particular migration efforts are required. + +[![Status: superseded](https://badgen.net/static/Status/superseded/purple)](https://gitlab.com/opensavvy/playgrounds/baseline/-/blob/main/docs/design/README.md#creating-a-new-record) • This decision was active, but was superseded by another decision. New code should follow the new decision. Existing code, when possible, should be migrated to follow the new decision. The field "Superseded by" should be present. + +**Discussion:** +When in "draft" status, links to an issue, a merge request, or some other type of document that allows comments. Any questions from the discussion that isn't answered by the record should be added to the record. When a record graduates and becomes active, the discussion link may remain for archival purposes (an active record is not subject to discussion, except when creating a new superseding record). + +**Superseded by:** +Links to one or more record which overturn the current record. Only presents when the status is "superseded". + +**Related to:** +Links to other records which have a related subject. + +**The problem.** +Exhaustive and precise description of the problem·s to solve. + +**Constraints.** +Additional constraints that are not intrinsic to the problem but may still impact decision-making. For example, a constraint on development time. + +**Considered solutions.** +Each considered solution should have its own section, containing: +- A description of what it would entail, +- A list of advantages compared to other solutions, +- A list of disadvantages compared to other solutions. + +The advantages and disadvantages may be subjective, as long as they are appropriate in the context of the problem. For example, "no one in the team has used this technology" is an appropriate disadvantage to using it, even if it seems completely appropriate otherwise. + +The selected solution should be included in this section, with the same content as all other alternatives. + +**Selected solution.** +Describes the selected solution in more details, and explains why it was selected (especially if other solutions have advantages that this one doesn't). + +## How are decision records modified? + +Unless to edit their status, records should almost never be edited. + +## What happens when a decision is overturned? + +If a decision is overturned, a new record should be created with the new decision, linking to the previous one. The previous one should be marked as Superseded. + +## When are decision records deleted? + +Decision records may only be deleted when **no content from to the repository whatsoever** uses them anymore, and **no future content should follow them**. At this point, and only at this point, are they truly useless, and thus worthy of deletion. + +As long as a single piece of code, static resources or anything else committed to the repository follows a design decision, it should remain in the repository as well. -- 2.51.2 From c3d1c7200c9db5eb63bbbfef7e67602e46808e69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 19:34:49 +0200 Subject: [PATCH 13/21] docs: Link useful external guides in the ADR file --- docs/design/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/design/README.md b/docs/design/README.md index 5da2acb..3eccf97 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -50,6 +50,8 @@ Here is a template for new records: ## Selected solution ``` +Useful external links: [How to write ADRs](https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.html), [How to review ADRs](https://www.ozimmer.ch/practices/2023/04/05/ADRReview.html). + The following describes all the fields of the template and what they should be filled in with. **Status:** -- 2.51.2 From 9856e59285f06f533690e4d3dffae7e3e90dd3f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 19:53:33 +0200 Subject: [PATCH 14/21] build(idea): Run configuration to run the mkdocs website locally --- .../Documentation_website.xml | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .idea/runConfigurations/Documentation_website.xml diff --git a/.idea/runConfigurations/Documentation_website.xml b/.idea/runConfigurations/Documentation_website.xml new file mode 100644 index 0000000..1c2fb07 --- /dev/null +++ b/.idea/runConfigurations/Documentation_website.xml @@ -0,0 +1,28 @@ +<component name="ProjectRunConfigurationManager"> + <configuration default="false" name="Documentation website" type="docker-deploy" factoryName="docker-image" server-name="Docker"> + <deployment type="docker-image"> + <settings> + <option name="imageTag" value="squidfunk/mkdocs-material" /> + <option name="containerName" value="" /> + <option name="portBindings"> + <list> + <DockerPortBindingImpl> + <option name="containerPort" value="8000" /> + <option name="hostPort" value="7999" /> + </DockerPortBindingImpl> + </list> + </option> + <option name="volumeBindings"> + <list> + <DockerVolumeBindingImpl> + <option name="containerPath" value="/docs" /> + <option name="hostPath" value="$PROJECT_DIR$/docs/website" /> + <option name="readOnly" value="true" /> + </DockerVolumeBindingImpl> + </list> + </option> + </settings> + </deployment> + <method v="2" /> + </configuration> +</component> \ No newline at end of file -- 2.51.2 From e1eea66eeae2979ea9395f6e7fe9b23cc38b314f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 19:59:24 +0200 Subject: [PATCH 15/21] docs(website): Fix the edition link --- docs/website/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 787b9ef..a8c5edb 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -37,4 +37,4 @@ theme: edit: material/pencil view: material/eye -edit_uri: edit/main/docs/website +edit_uri: edit/main/docs/website/docs -- 2.51.2 From 1aa7b3aa2f7064d063794c12045aeb40f2bece14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 20:21:19 +0200 Subject: [PATCH 16/21] docs(website): Add OpenSavvy logo --- docs/website/docs/assets/logo.svg | 127 ++++++++++++++++++++++++++++++ docs/website/mkdocs.yml | 2 + 2 files changed, 129 insertions(+) create mode 100644 docs/website/docs/assets/logo.svg diff --git a/docs/website/docs/assets/logo.svg b/docs/website/docs/assets/logo.svg new file mode 100644 index 0000000..3c87a67 --- /dev/null +++ b/docs/website/docs/assets/logo.svg @@ -0,0 +1,127 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:xlink="http://www.w3.org/1999/xlink" + width="400" + height="400" + viewBox="0 0 400 400" + version="1.1" + id="svg1" + xmlns="http://www.w3.org/2000/svg"> + <defs + id="defs1"> + <linearGradient + id="linearGradient6"> + <stop + style="stop-color:#4d249a;stop-opacity:1;" + offset="0" + id="stop5"/> + <stop + style="stop-color:#972aa7;stop-opacity:1;" + offset="1" + id="stop6"/> + </linearGradient> + <linearGradient + id="linearGradient1"> + <stop + style="stop-color:#5226a2;stop-opacity:1;" + offset="0" + id="stop1"/> + <stop + style="stop-color:#852da0;stop-opacity:1;" + offset="1" + id="stop2"/> + </linearGradient> + <linearGradient + id="linearGradient13"> + <stop + style="stop-color:#0b8bea;stop-opacity:1;" + offset="0" + id="stop13"/> + <stop + style="stop-color:#11d2ed;stop-opacity:1;" + offset="1" + id="stop14"/> + </linearGradient> + <linearGradient + xlink:href="#linearGradient13" + id="linearGradient14" + x1="241.17003" + y1="283.41473" + x2="242.69476" + y2="105.93424" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1.2715214,0,0,1.2715214,-52.39746,-43.00102)"/> + <linearGradient + xlink:href="#linearGradient1" + id="linearGradient2" + x1="156.07582" + y1="3.1215208" + x2="251.95094" + y2="399.10815" + gradientUnits="userSpaceOnUse"/> + <linearGradient + xlink:href="#linearGradient13" + id="linearGradient3" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1.2715214,0,0,1.2715214,-49.761695,-40.852208)" + x1="241.17003" + y1="283.41473" + x2="242.69476" + y2="105.93424"/> + <linearGradient + xlink:href="#linearGradient6" + id="linearGradient5" + gradientUnits="userSpaceOnUse" + x1="156.07582" + y1="3.1215208" + x2="251.95094" + y2="399.10815" + gradientTransform="matrix(1.4200707,0,0,1.4200707,-84.053693,-83.525091)"/> + </defs> + <!-- region Main text --> + <g + id="layer1" + style="display:inline"> + + <!-- Main O --> + <text + xml:space="preserve" + style="font-size:305.166px;font-family:'JetBrains Mono';-inkscape-font-specification:'JetBrains Mono';display:inline;fill:#000000;stroke:#0f1893;stroke-width:1.27407;stroke-dasharray:none;stroke-opacity:1" + x="58.169628" + y="315.91675" + id="text1"><tspan + id="tspan1" + x="58.169628" + y="315.91675" + style="stroke-width:1.27407"><tspan + style="font-size:305.166px;fill:#0f1893;fill-opacity:1;stroke:#0f1893;stroke-width:1.27407;stroke-dasharray:none;stroke-opacity:1" + id="tspan2">O</tspan><tspan + style="font-size:305.166px;fill:#0980f3;fill-opacity:1;stroke:#0f1893;stroke-width:1.27407;stroke-opacity:1" + id="tspan3"/></tspan></text> + + <!-- Main S --> + <text + xml:space="preserve" + style="font-size:305.166px;font-family:'JetBrains Mono';-inkscape-font-specification:'JetBrains Mono';display:inline;fill:url(#linearGradient14);stroke-width:1.27407;stroke-dasharray:none" + x="164.80923" + y="315.91705" + id="text1-2"><tspan + id="tspan1-9" + x="164.80923" + y="315.91705" + style="fill:url(#linearGradient14);stroke-width:1.27407"><tspan + style="font-size:305.166px;fill:url(#linearGradient14);fill-opacity:1;stroke-width:1.27407" + id="tspan3-9">S</tspan></tspan></text> + </g> + <!-- endregion --> + <!-- region Mask --> + <g + id="layer2" + style="display:inline"> + <path + id="text1-5" + style="font-size:240px;font-family:'JetBrains Mono';-inkscape-font-specification:'JetBrains Mono';fill:#0f1893;fill-opacity:1;stroke-width:1.27407;stroke-dasharray:none" + d="m 112.15281,199.26602 c -2.23925,0.0681 -4.47848,0.14488 -6.7177,0.2111 -6.913168,0.20558 -13.830535,0.37614 -20.746668,0.57119 v 51.99579 c 0,21.56491 5.797795,38.14709 17.394018,49.74331 11.59622,11.59622 27.36473,17.39402 47.30208,17.39402 19.93735,0 35.70338,-5.7978 47.29961,-17.39402 11.59622,-11.59622 17.39401,-28.1784 17.39401,-49.74331 v -45.25325 c -2.75802,0.18397 -5.52806,0.24679 -8.28724,0.25083 -6.40343,-0.0823 -12.79486,-0.37984 -19.17712,-0.82698 v 48.88155 c 0,12.61344 -3.25475,22.38011 -9.76489,29.29714 -6.30675,6.71363 -15.46126,10.07034 -27.46437,10.07034 -11.79967,0 -20.95671,-3.35671 -27.46685,-10.07034 -6.51019,-6.91703 -9.76488,-16.6837 -9.76488,-29.29714 z"/> + </g> + <!-- endregion --> +</svg> diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index a8c5edb..da9930a 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -36,5 +36,7 @@ theme: icon: edit: material/pencil view: material/eye + logo: assets/logo.svg + favicon: assets/logo.svg edit_uri: edit/main/docs/website/docs -- 2.51.2 From e39f9a578bf8ffef3137f794109be7190d0faee5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 20:21:39 +0200 Subject: [PATCH 17/21] docs(website): Enable line selection for code samples --- docs/website/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index da9930a..33ee70c 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -11,7 +11,7 @@ theme: - content.action.view - content.code.annotate - content.code.copy - # - content.code.select + - content.code.select # - content.footnote.tooltips # - content.tabs.link - content.tooltips -- 2.51.2 From d812bb787d527f75b2b8463a637144d49870a1ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 20:26:47 +0200 Subject: [PATCH 18/21] docs(website): Let the user select between light and dark themes --- docs/website/mkdocs.yml | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 33ee70c..67b89ad 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -38,5 +38,20 @@ theme: view: material/eye logo: assets/logo.svg favicon: assets/logo.svg + palette: + - media: "(prefers-color-scheme)" + toggle: + icon: material/brightness-auto + name: "System theme (click to switch to light)" + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/brightness-7 + name: "Light theme (click to switch to dark)" + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/brightness-4 + name: "Dark theme (click to switch to system)" edit_uri: edit/main/docs/website/docs -- 2.51.2 From 47d143b15514b7b95d7e1769b9e2c7df80210fbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 20:35:18 +0200 Subject: [PATCH 19/21] docs(website): Use the OpenSavvy color palette (approximately) --- docs/website/mkdocs.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 67b89ad..77bcc3d 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -45,11 +45,15 @@ theme: name: "System theme (click to switch to light)" - media: "(prefers-color-scheme: light)" scheme: default + primary: deep purple + accent: cyan toggle: icon: material/brightness-7 name: "Light theme (click to switch to dark)" - media: "(prefers-color-scheme: dark)" scheme: slate + primary: deep purple + accent: cyan toggle: icon: material/brightness-4 name: "Dark theme (click to switch to system)" -- 2.51.2 From bed23ddca0ec5bf8794439cf511bc21cfa695817 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 20:37:27 +0200 Subject: [PATCH 20/21] docs(website): Create the main tabs --- docs/website/mkdocs.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 77bcc3d..98813dd 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -59,3 +59,12 @@ theme: name: "Dark theme (click to switch to system)" edit_uri: edit/main/docs/website/docs + +nav: + - Home: index.md + + - Getting started: [] + + - Module1: [] + + - Module2: [] -- 2.51.2 From 2c62272aae410cc693c0cc4f931a239673dace8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20=E2=80=9CCLOVIS=E2=80=9D=20Canet?= <ivan.canet@gmail.com> Date: Thu, 25 Apr 2024 21:48:35 +0200 Subject: [PATCH 21/21] docs(website): Custom home page --- docs/website/docs/index.md | 6 +++- docs/website/mkdocs.yml | 1 + docs/website/overrides/home.html | 61 ++++++++++++++++++++++++++++++++ 3 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 docs/website/overrides/home.html diff --git a/docs/website/docs/index.md b/docs/website/docs/index.md index ceea72a..4f5ca0b 100644 --- a/docs/website/docs/index.md +++ b/docs/website/docs/index.md @@ -1,3 +1,7 @@ -# Home +--- +template: home.html +--- + +# Welcome! The OpenSavvy Playground is a project template with pre-configured CI/CD, documentation generator, etc. diff --git a/docs/website/mkdocs.yml b/docs/website/mkdocs.yml index 98813dd..112d0f9 100644 --- a/docs/website/mkdocs.yml +++ b/docs/website/mkdocs.yml @@ -5,6 +5,7 @@ site_description: > theme: name: material + custom_dir: overrides features: - announce.dismiss - content.action.edit diff --git a/docs/website/overrides/home.html b/docs/website/overrides/home.html new file mode 100644 index 0000000..29eaa5e --- /dev/null +++ b/docs/website/overrides/home.html @@ -0,0 +1,61 @@ +{% extends "main.html" %} +{% block tabs %} +{{ super() }} +<style> + #hero-page { + height: 100vh; + margin-left: 1rem; + margin-right: 1rem; + } + + #hero-title { + font-size: 3.7rem; + margin-top: 30vh; + margin-bottom: 1rem; + font-weight: bolder; + } + + @media screen and (min-width: 60em) { + .md-sidebar--secondary { + display: none + } + } + + @media screen and (min-width: 76.25em) { + .md-sidebar--primary { + display: none + } + } +</style> + +<section id="hero-page" class="mdx-container"> + <div class="md-typeset"> + <div class="mdx-hero"> + <div class="mdx-hero__content"> + <h1 id="hero-title">{{ config.site_name }}</h1> + + <p>{{ config.site_description }}</p> + + <div> <!-- Badges --> + + <a href="https://discord.gg/48Wv6BkJx6"><img src="https://img.shields.io/badge/Discuss-Discord-7289da"></a> + </div> + + <a href="{{ page.next_page.url | url }}" title="{{ page.next_page.title | e }}" + class="md-button md-button--primary"> + Quick start + </a> + <a href="{{ config.repo_url }}" title="Material for MkDocs Insiders" class="md-button"> + Visit repository + </a> + </div> + </div> + </div> +</section> +{% endblock %} + +{% block content %} +<div style="min-height: 50vh"> + {{ super() }} +</div> +{% endblock %} -- 2.51.2