Merge branch 'how-to-contribute' into 'master'

How to contribute

See merge request !7

docs/about-us.md → docs/about-us/docs/about-us.md

 ---
 hide:
-  - navigation
   - toc
   - breadcrumbs
 ---

docs/about-us/docs/contribute/overview.md

+# Documentation overview
+
+## Structure of the 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
+.
+├── docs
+│   ├── about-us
+|   |   |-- docs
+│   │   └── mkdocs.yml
+│   ├── ...
+│   ├── compute
+│   │   ├── concepts
+|   |   |   |-- docs
+|   |   |   └── mkdocs.yml
+|   |   |-- ...
+│   │   └── supercomputing
+|   |       |-- docs
+|   |       └── mkdocs.yml
+│   └── assets
+│       ├── css
+│       └── js
+|── e-infra_theme
+|── mkdocs.yml
+```
+
+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
+
+The most important part of the child documentation is `mkdocs.yml` file, where the navigation and structure of the documentation is defined. The important options are:
+```yml title="Example of mkdocs.yml"
+site_name: "computing/cloud/openstack"
+nav:
+    - 'index.md'
+    - 'about.md'
+```
+
+## Building documentation
+
+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
+[3]: ../push-contribution-to-the-repository
\ No newline at end of file

docs/about-us/docs/contribute/set-up-and-work-localy.md

+# Set up and work localy
+
+There are several ways to contribute to the documentation
+based on the user's proficiency with Git/GitLab. From the least to most proficient, these are:    
+
+- [Forking Repository](#forking-repository)    
+- [Simple Merge Request (using GitLab web interface)](/#simple-merge-request-using-gitlab-web-interface)    
+
+## Prerequisites
+- [Git][1]
+- [Docker][2]
+
+## Forking Repository
+
+### Fork Repository
+See GitLab @ ICS MU for details. This will create your own clone of our repository where you will be able to make changes. Once you are happy with your changes, use GitLab to submit them to our original repository.
+
+### Clone Repository
+
+```console
+# after creating your own copy of the repository on GitLab
+git clone git@gitlab.ics.muni.cz:einfra-docs/documentation.git
+```
+
+### Create New Branch
+
+```console
+# in `documentation` folder
+git checkout -b my_change
+```
+
+### Make Changes & Run Local Server
+
+Use our `start.sh`, which will use our production [Docker][4] container and will create production version server of the documentation locally on your PC.
+```console
+# in `mkdocs-material`
+./start.sh
+```
+
+!!! 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

docs/about-us/docs/contribute/style.md

+# Documentation style
+
+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

docs/about-us/docs/contribute/work-within-gitlab-ui.md

+# 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

docs/about-us/docs/contribute/writing-practices.md

+# Best Practices for Writing Doc
+
+This section contains conventions and best practices for writing the best possible documentation.
+
+!!! note
+    The section is work in progress.
+
+## Passing Test in Doc Build
+
+Each pipeline starts with four test jobs:
+
+1. **capitalize** - checks capitalization of (sub)titles. Every word should start with a capital letter except for prepositions. Non-standard words with mixed lower- and uppercase letters (e.g. eINFRA) should be added to the *.spelling* file.
+
+1. **docs** - checks some standard rules of formatting to make the source code more "readable".
+The most important being: **trailing spaces** (multiple spaces at the EOL), **consecutive blank lines** or,
+alternatively, **missing blank lines** (each element -- admonition, codeblock, (sub)title, img link -- must be divided by a blank line).
+
+1. **pylint** - don't know, but always passes :)
+
+1. **pysafety** - related to missing security update for the tornado package, always fails (is allowed to fail)
+
+## Contribution and Revision Process
+
+TODO. Here we should write down some processess for revisions and merging requests for change.

docs/about-us/mkdocs.yml

+site_name: "about"
+
+nav:
+  - Overview: about-us.md
+  - 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

mkdocs.yml

@@ -62,7 +62,7 @@ nav:
     - SensitiveCloud: '!include ./docs/compute/sensitive/mkdocs.yml'
   - Storage: '!include ./docs/storage/mkdocs.yml'
   - Managed services: '!include ./docs/managed/mkdocs.yml'
-  - About Us: about-us.md
+  - General Information: '!include ./docs/about-us/mkdocs.yml'
 
 #extra:
 #  disqus: 'test-3whnesz3gq'