From 6835e5fbea1e9fee1a9ed0798fad64da527c9b04 Mon Sep 17 00:00:00 2001
From: Adrian Rosinec <adrian@ics.muni.cz>
Date: Sun, 31 Jul 2022 19:12:37 +0200
Subject: [PATCH] Update how to contribute
---
docs/about-us/docs/contribute/overview.md | 13 +++++--
.../push-contribution-to-the-repository.md | 36 -------------------
.../docs/contribute/set-up-and-work-localy.md | 26 ++++++++++++--
docs/about-us/docs/contribute/style.md | 6 ++--
.../docs/contribute/work-within-gitlab-ui.md | 17 +++++++++
docs/about-us/mkdocs.yml | 1 +
6 files changed, 56 insertions(+), 43 deletions(-)
delete mode 100644 docs/about-us/docs/contribute/push-contribution-to-the-repository.md
create mode 100644 docs/about-us/docs/contribute/work-within-gitlab-ui.md
diff --git a/docs/about-us/docs/contribute/overview.md b/docs/about-us/docs/contribute/overview.md
index 8dcccdbe..6c24200a 100644
--- a/docs/about-us/docs/contribute/overview.md
+++ b/docs/about-us/docs/contribute/overview.md
@@ -1,7 +1,7 @@
# Documentation overview
## Structure of the documentation
-Thanks to the [Monorepo][1] plugin for the mkdocs platform, it is possible to enable a documentation structure consisting of sub-topic-related documentation.
+Thanks to the [Monorepo][1] plugin for the mkdocs platform, it is possible to create a documentation structure consisting of sub-topic-related documentation.
The documentation is organized to categories (2nd level folders) and topics (3rd level folders). See following output for reference.
```console
@@ -26,7 +26,7 @@ The documentation is organized to categories (2nd level folders) and topics (3rd
|── mkdocs.yml
```
-Earch e-INFRA service is represented by it's own topic, therefore folder structure consisting of `mkdocs.yml` file and `docs` folder.
+Each e-INFRA service is represented by it's own topic, therefore folder structure consisting of `mkdocs.yml` file and `docs` folder.
## Documentation configuration - mkdocs.yml
@@ -44,6 +44,13 @@ It is possible to build whole documentation or just it's small fraction.
[See how to build documentation here][2].
+## Publishing changes
+
+Once the changes to the documentation has beed made locally or within the Gitlab graphical editor, it is important to publish it a make it visible on the main documentation domain. The changes will go through automatic checks and final review of our editor staff.
+
+[Please refer to this documentation page to see how][3]
+
[1]: https://github.com/backstage/mkdocs-monorepo-plugin
-[2]: ./set-up-and-work-localy
\ No newline at end of file
+[2]: ../set-up-and-work-localy
+[3]: ../push-contribution-to-the-repository
\ No newline at end of file
diff --git a/docs/about-us/docs/contribute/push-contribution-to-the-repository.md b/docs/about-us/docs/contribute/push-contribution-to-the-repository.md
deleted file mode 100644
index 4b2d45f2..00000000
--- a/docs/about-us/docs/contribute/push-contribution-to-the-repository.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Publish changes to the main repository
-
-### Commit and Push Changes
-
-If you are satisfied with your changes and you did build the whole documentation to review you changes in the context of the whole site commit and push changes to main respository:
-
-```console
-git commit -am "Commit message"
-git push --set-upstream origin my_change
-```
-
-### Submit Changes
-
-Create a *Merge Request* via GitLab @ ICS MU.
-
-## Simple Merge Request (using GitLab web interface)
-
-This option is suitable for less extensive contribution
-(e.g. a section or a subsection) of an already existing page).
-
-In this case, simply:
-
-1. click the **Edit this page**
-under the Table of Content on the right side of the respective page;
-1. make the changes;
-1. create a merge request.
-
-## Contacting Support
-
-The easiest way is to contact us at [support@e-infra.cz][3] with your contribution.
-
-[1]: https://github.com/squidfunk/mkdocs-material
-[2]: https://squidfunk.github.io/mkdocs-material/getting-started/
-[3]: mailto:support@e-infra.cz
-[4]: https://git-scm.com/downloads
-[5]: https://docs.docker.com/get-docker/
\ No newline at end of file
diff --git a/docs/about-us/docs/contribute/set-up-and-work-localy.md b/docs/about-us/docs/contribute/set-up-and-work-localy.md
index 49a803d5..ae294e44 100644
--- a/docs/about-us/docs/contribute/set-up-and-work-localy.md
+++ b/docs/about-us/docs/contribute/set-up-and-work-localy.md
@@ -7,8 +7,8 @@ based on the user's proficiency with Git/GitLab. From the least to most proficie
- [Simple Merge Request (using GitLab web interface)](/#simple-merge-request-using-gitlab-web-interface)
## Prerequisites
-- [Git][4]
-- [Docker][5]
+- [Git][1]
+- [Docker][2]
## Forking Repository
@@ -40,7 +40,29 @@ Use our `start.sh`, which will use our production [Docker][4] container and will
!!! note
Edits will be shown live in your browser window, no need to restart the server.
+### Partial documentation building
+
If you don't want to build the whole documentation (due to it's big build time), you can choose to build only subset of the whole documentation site by using argument `-f <path to mkdocs.yml of subdocumnetation>`
```console
./start.sh -f /docs/compute/kubernetes/mkdocs.yml
```
+
+### Publishing changes
+
+#### Commit and Push Changes
+
+If you are satisfied with your changes and you did build the whole documentation to review you changes in the context of the whole site commit and push changes to main respository:
+
+```console
+git commit -am "Commit message"
+git push --set-upstream origin my_change
+```
+
+#### Submit Changes
+
+Create a *Merge Request* via GitLab @ ICS MU.
+
+[1]: https://git-scm.com/downloads
+[2]: https://docs.docker.com/get-docker/
+[3]: https://docs.e-infra.cz
+[4]: ../push-contribution-to-the-repository
\ No newline at end of file
diff --git a/docs/about-us/docs/contribute/style.md b/docs/about-us/docs/contribute/style.md
index 6518c25a..ed17d49c 100644
--- a/docs/about-us/docs/contribute/style.md
+++ b/docs/about-us/docs/contribute/style.md
@@ -1,4 +1,6 @@
# Documentation style
-1. A
-2. B
\ No newline at end of file
+This section focuses on the best practise of usage of various components (code blocks, notes, diagrams, ...) used within the documentation.
+
+!!! note
+ The section is work in progress, please, be patient.
\ No newline at end of file
diff --git a/docs/about-us/docs/contribute/work-within-gitlab-ui.md b/docs/about-us/docs/contribute/work-within-gitlab-ui.md
new file mode 100644
index 00000000..528075df
--- /dev/null
+++ b/docs/about-us/docs/contribute/work-within-gitlab-ui.md
@@ -0,0 +1,17 @@
+# Contribute within Gitlab GUI
+
+## Simple Merge Request (using GitLab web interface)
+
+This option is suitable for less extensive contribution
+(e.g. a section or a subsection) of an already existing page).
+
+In this case, simply:
+
+1. click the **Edit this page**
+under the Table of Content on the right side of the respective page;
+1. make the changes;
+1. create a merge request.
+
+## Contacting Support
+
+The easiest way is to contact us at [support@e-infra.cz][3] with your contribution.
\ No newline at end of file
diff --git a/docs/about-us/mkdocs.yml b/docs/about-us/mkdocs.yml
index 30b98239..f8361684 100644
--- a/docs/about-us/mkdocs.yml
+++ b/docs/about-us/mkdocs.yml
@@ -5,5 +5,6 @@ nav:
- e-INFRA contributor guide:
- Overview: ./contribute/overview.md
- Set up and work localy: ./contribute/set-up-and-work-localy.md
+ - Work within the GitLab UI: ./contribute/work-within-gitlab-ui.md
- Writing practices: ./contribute/writing-practices.md
- Style guide: ./contribute/style.md
\ No newline at end of file
--
GitLab