Skip to content
Snippets Groups Projects
Commit c01f16bd authored by Adrián Rošinec's avatar Adrián Rošinec
Browse files

Merge branch 'how_to_contribute_2' into 'master'

How to contribute

See merge request !10
parents b72f6d20 751ded1e
No related branches found
No related tags found
1 merge request!10How to contribute
Pipeline #178439 passed with warnings
Showing
with 300 additions and 59 deletions
......@@ -97,7 +97,7 @@ a:not([href*="//"]) {
/* CSS for internal links */
}
a[href*="//"]:not( [href*='127.0.0.1'] ):not( [href*='docs.it4i.cz'] ):not( [href*='gitlab.it4i.cz'] ):not( [href*='code.it4i.cz'] ):not( [href*='https://www.it4i.cz'] ):not( [href*='https://support.it4i.cz'] ):not( [href*='docs.e-infra.cz'] ) {
a[href*="//"]:not( [href*='127.0.0.1'] ):not( [href*='docs.it4i.cz'] ):not( [href*='gitlab.it4i.cz'] ):not( [href*='code.it4i.cz'] ):not( [href*='https://www.it4i.cz'] ):not( [href*='https://e-infra.cz'] ):not( [href*='https://support.it4i.cz'] ):not( [href*='docs.e-infra.cz'] ):not( [href*='gitlab.ics.muni.cz'] ) {
background: transparent no-repeat right 0px top 1px;
background-size: 12px;
padding: 0px 16px 1px 0px;
......
(function(h,o,t,j,a,r){
h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
h._hjSettings={hjid:3103171,hjsv:6};
a=o.getElementsByTagName('head')[0];
r=o.createElement('script');r.async=1;
r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
a.appendChild(r);
})(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
var _paq = window._paq = window._paq || [];
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="//analytics.cerit-sc.cz/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '1']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
\ No newline at end of file
......@@ -7,11 +7,12 @@ extra_css:
extra_javascript:
- https://unpkg.com/mermaid@7.0.5/dist/mermaid.min.js
- assets/js/hotjar.js
# Repository
repo_name: einfra-docs/documentation
repo_url: https://gitlab.ics.muni.cz/einfra-docs/documentation/
edit_uri: edit/master/docs/
edit_uri: edit/master/
# Copyright
copyright: Copyright (c) 2021-2022 e-infra.cz - documentation portal
......@@ -104,7 +105,11 @@ markdown_extensions:
custom_checkbox: true
- pymdownx.tilde
- footnotes
- pymdownx.superfences
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
......
topics/about-us/docs/contribute/assets/overview.png

188 KiB

topics/about-us/docs/contribute/assets/signpost.png

71 KiB

topics/about-us/docs/contribute/assets/standard.png

88 KiB

# 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)
One of the mechanisms to work with the documentation is to run it on your computer using Docker. This allows you to work offline and see the documentation rendered in a web browser.
## 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.
## Fork Repository
Fork the [e-INFRA CZ documentation repository][3]. This will create your own clone of upstream e-INFRA CZ documetation 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
## 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
## Create New Branch
At the moment there is no convention on how to name the feature branches. Try to make clear what feature will be added within the new branch.
```console
# in `documentation` folder
git checkout -b my_change
```
### Make Changes & Run Local Server
## 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.
You can edit the documentation and run local server to see changes live. Use our `start.sh`, which will use our production [Docker][2] container and will create production version server of the documentation locally on your PC. Then go to [http://localhost:8080][4] to see changes, from now, every change will reload the page in the browser automaticaly.
```console
# in `mkdocs-material`
./start.sh
```
By default the URL where the server [listen is http://localhost:8080][4]
!!! note
Edits will be shown live in your browser window, no need to restart the server.
......@@ -44,12 +40,13 @@ Use our `start.sh`, which will use our production [Docker][4] container and will
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
./start.sh -f topics/about-us/mkdocs.yml
```
### Publishing changes
## Publishing changes
#### Commit and Push Changes
Now you are ready to send changes to your forked repository of the e-INFRA CZ documentation.
### 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:
......@@ -58,11 +55,12 @@ git commit -am "Commit message"
git push --set-upstream origin my_change
```
#### Submit Changes
### Submit Changes
Create a *Merge Request* via GitLab @ ICS MU.
Create a *Merge Request* via GitLab @ ICS MU to send __your__ changes to __upstream__ repository. Please refer to the tutorial on how to create merge request to upstream repository at [Gitlab documentation][5].
[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
[3]: https://gitlab.ics.muni.cz/einfra-docs/documentation
[4]: http://localhost:8080
[5]: https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html#merging-upstream
\ No newline at end of file
# 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).
......@@ -14,4 +12,6 @@ under the Table of Content on the right side of the respective page;
## Contacting Support
The easiest way is to contact us at [support@e-infra.cz][3] with your contribution.
\ No newline at end of file
The easiest way is to contact us at [support@e-infra.cz][1] with your contribution.
[1]: mailto:support@e-infra.cz
\ No newline at end of file
---
hide:
- toc
authors:
- rosinec
---
# 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.
This section is about how to contribute to the e-INFRA CZ documentation. The guide is intended for service providers but also for users of the documentation and e-INFRA CZ services, who can participate in building the documentation and thus help other users.
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
```
For service providers, a detailed specification of how the documentation is built and works can be useful.
Each e-INFRA service is represented by it's own topic, therefore folder structure consisting of `mkdocs.yml` file and `docs` folder.
<div class="grid cards" markdown>
## Documentation configuration - mkdocs.yml
- :fontawesome-solid-server:{ .md .middle } __Open to contributions__
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
Anyone can contribute. You can work with web editor or run whole documentation on your PC.
It is possible to build whole documentation or just it's small fraction.
[:octicons-arrow-right-24: Contribute within web editor](../contributing/work-within-gitlab-ui)
[:octicons-arrow-right-24: Contribute locally](../contributing/set-up-and-work-localy)
[See how to build documentation here][2].
- :fontawesome-solid-microchip:{ .md .middle } __Technical details__
## 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.
All technical information about the documentation. Targets e-INFRA CZ service providers.
[Please refer to this documentation page to see how][3]
[:octicons-arrow-right-24: Technical details](../technical-details)
[:octicons-arrow-right-24: Integration of the new service](../technical-details/#integration-of-the-new-service)
- :fontawesome-solid-atom:{ .md .middle } __Language of the documentation__
[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
---
How to write documentation to make it useful, and what elements are available.
[:octicons-arrow-right-24: Writing practices](../style-guide/writing-practices)
[:octicons-arrow-right-24: Style](../style-guide/style)
</div>
\ No newline at end of file
# 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.
### Metadata
Every page might have the metadata modyfing how page is rendered or what information the page has.
For example, it is possible to simulate page layouts or store authors.
## Page Layouts
The e-INFRA CZ recognizes three types of page layout:
=== "SignPost"
![Page Layout: SignPost](../assets/signpost.png){ loading=lazy width="49.9%" align=left }
SignPost's role is to introduce the depth of each topic. It should easily categorize main structure of the topic.
__SignPost's primary feature__ is that it has removed **Table of concents** on the right side.
__Usage:__
Copy this on beggining of each page to hide ToC
``` markdown
---
hide:
- toc
---
```
=== "Standard"
![Page Layout: Standard](../assets/standard.png){ loading=lazy width="49.9%" align=left }
Standard page is default template and it's used for standard documentation pages.
=== "Overview"
![Page Layout: Overview](../assets/overview.png){ loading=lazy width="49.9%" align=left }
Used only for 'special' ocassions such as home page. It has both navigation menu and table of content hidden, providing wide space for content.
__Usage:__
Copy this on beggining of the page to create overview layout
``` markdown
---
hide:
- toc
- nav
---
```
## Authors
If you want to be featured as maintainer of the page use this in metadata:
``` markdown
---
authors
- <github_username>
- ...
---
```
## Hiding breadcrumbs
It is possible to hide __breadcrumbs__ by adding to metadata:
``` markdown
---
hide:
- breadcrumbs
---
```
\ No newline at end of file
......@@ -5,6 +5,19 @@ This section contains conventions and best practices for writing the best possib
!!! note
The section is work in progress.
## Authoring and responsibility
Each topic has responsible department or person which will be responsible for approving changes.
| Area | Responsible |
| ----------- | ------------------------------------ |
| Homepage, navigation, general site | @rosinec, Jan Siwiec |
| Accounts | Pavel Zlamal |
| Data processing | @rosinec |
| Data storage | du.cesnet.cz |
| Managed Data Services | @rosinec |
| General Information | @rosinec, Jan Siwiec |
## Passing Test in Doc Build
Each pipeline starts with four test jobs:
......
# 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
# Technical details
Technical details for nerds.
## 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 topics.
```console
.
├── topics
│ ├── about-us
| | |-- docs
│ │ └── mkdocs.yml
│ ├── storage
│ └── compute
│ ├── concepts
| | |-- docs
| | └── mkdocs.yml
| |-- ...
│ └── supercomputing
| |-- docs
| └── mkdocs.yml
|── docs
│ └── assets
│ ├── css
│ └── js
|── e-infra_theme
└── mkdocs.yml
```
Each e-INFRA service is represented by it's own topic, therefore folder structure consists of `topics`, `docs`, `mkdocs.yml` file and `e-infra_theme` folder. Which are essential files in the documentation system.
## 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" # will be used in URL
nav:
- 'index.md'
- 'about.md'
```
## Using Git Submodules
The documentation can be composed from different git repositories thanks to the `git submodules` concept. To add new submodule, use standard `git submodule` commands.
The resulting file, where submodule should be registered is `.gitsubmodule`. Example of such file can be observed within the documentation project in the root directory (or in following code snippet).
!!! warning
The changes in the submodule at the source location can't trigger CI/CD pipeline of e-INFRA CZ documentation. However the pipeline is being run periodicaly in the midnight.
```config title="Example of .gitmodules"
[submodule "user/awesome_project"]
path = topics/compute/supercomputing/docs
url = https://<username>:<deploy_token>@gitlab.example.com/user/awesome_project.git
```
Use `topics/compute/supercomputing` as current working example of how to use the `git submodules`.
## Integration of the new service
As service owner you can easily integrate your service documentation within the main repository or use submodule.
To establish right place for the service documentation, please contact us at support@e-infra.cz.
## Development process
The development process of the documentation is supported by CI/CD. Each commit to any remote branch will trigger an automatic pipeline that will try deploy changed documentation to the desired location.
Pipeline consists of:
1. Various test, see more at [writing practices page][2]
1. Building documentation - runinng `mkdocs build`
1. Pushing resulted artifact (final documentation site) to:
1. If changes were pushed to the __main__ branch, the site is deployed to the **docs.e-infra.cz** immidiately.
2. If changes were pushed to the __any other__ branch, the site is deployed to the special URL for review - **docs.e-infra.cz/review/branch_name**
Please note, the pipeline is being run also 10 minutes after midnight each day to ensure, that submodule components of the documentation are being updated.
[1]: https://github.com/backstage/mkdocs-monorepo-plugin
[2]: ../style-guide/writing-practices
\ No newline at end of file
site_name: "about"
edit_uri: edit/master/topics/about-us/docs
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
- Contributing:
- Set up and work localy: ./contribute/contributing/set-up-and-work-localy.md
- Work within the GitLab UI: ./contribute/contributing/work-within-gitlab-ui.md
- Style Guide:
- Writing practices: ./contribute/style-guide/writing-practices.md
- Style guide: ./contribute/style-guide/style.md
- Technical Details: ./contribute/technical-details.md
\ No newline at end of file
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment