add shortcodes and system roles section

site/README.md

@@ -25,17 +25,17 @@ the weight (affects the order of files display on the sidebar) and description (
 
 ### Start site localy
 
-To start the site locally, you need a recent [extended version hugo](https://github.com/gohugoio/hugo/releases)
+To start the site locally, you need a recent [extended version hugo](https://github.com/gohugoio/hugo/releases)
 (recommend version 0.75.0 or later).
-Open the most recent release and scroll down until you find a list of Extended versions. [Read more](https://gohugo.io/getting-started/installing/#quick-install)
+Open the most recent release and scroll down until you find a list of Extended versions. [Read more](https://gohugo.io/getting-started/installing/#quick-install)
 
 Add a path to "hugo" in the "Path" environment variable.
 
 Clone a repository branch containing the site. For example, using a git command:
 
     git clone --branch <branchname> <remote-repo-url>
 
-If you want to build and/or serve your site locally, you also need to get local copies of the theme’s own submodules:
+If you want to build and/or serve your site locally, you also need to get local copies of the theme's own submodules:
 
     git submodule update --init --recursive
 
@@ -44,11 +44,11 @@ To build and preview your site locally, use:
     cd <your local directory>/cvat/site/
     hugo server
 
-By default, your site will be available at <http://localhost:1313/docs/>.
+By default, your site will be available at <http://localhost:1313/docs/>.
 
 Instead of a "hugo server" command, you can use the "hugo" command that generates the site into a "public" folder.
 
-To build or update your site’s CSS resources you will need [PostCSS](https://postcss.org/) to create final assets.
+To build or update your site's CSS resources you will need [PostCSS](https://postcss.org/) to create final assets.
 To install it you must have a recent version of [NodeJS](https://nodejs.org/en/) installed on your machine,
 so you can use npm, the Node package manager.
 By default npm installs tools under the directory where you run [npm install](https://docs.npmjs.com/cli/v6/commands/npm-install#description):
@@ -77,3 +77,34 @@ Add and then commit the change to project:
 Push the commit to project repo. For example, run:
 
     git push
+
+### Site features
+
+#### Get CSV
+
+You can put a `CSV` spreadsheet in the documentation. To do this, use the shortcode:
+
+```go
+{{< get-csv url="<ur_or_path_to_csv_file>" sep="<sep>" >}}
+```
+
+You need to set the url of the csv file or the path in the repository
+(note that the root in this case will be the `site` folder in the repository,
+so if you want to insert the table from the directory above use `.. /..`).
+You can also set the separator (the default is `,`).
+
+#### Repolink
+
+You can add a link to a file or folder in the repository
+that will be bound to the documentation version using the repolink shortcode:
+
+``` go
+{{< repolink text="<text>" path="<path_into_repository>" icon="<true>" >}}
+```
+
+You must specify the text that will be displayed in the documentation, you can specify the path inside the repository
+(if you do not specify the path the link will lead to the root of the repository).
+If you want the link to be different from other links in the documentation you can include the GitHub icon
+for this add `icon='"` (by default the icon is not displayed).
+In order to set a link to a folder, the path must end with `/`
+The repository link is specified by the `github_repo` parameter in the `config.toml` file.

site/build_docs.py

@@ -41,6 +41,7 @@ def git_checkout(tagname, cwd):
     images_dir = os.path.join(cwd, 'site', 'content', 'en', 'images')
     shutil.rmtree(images_dir)
     repo.git.checkout(tagname, '--', 'site/content/en/images')
+    repo.git.checkout(tagname, '--', 'cvat/cvat/apps/iam/rules')
 
 def change_version_menu_toml(filename, version):
     data = toml.load(filename)

site/config.toml

@@ -28,6 +28,9 @@ pygmentsUseClassic = false
 # See https://help.farbox.com/pygments.html
 pygmentsStyle = "tango"
 
+# Ignore Errors
+ignoreErrors = ["error-remote-getcsv"]
+
 # Configure how URLs look like per section.
 [permalinks]
 blog = "/:section/:year/:month/:day/:slug/"

site/content/en/docs/administration/advanced/iam_system_roles.md

@@ -1,9 +1,70 @@
 ---
 title: 'IAM: system roles'
-linkTitle: 'system roles'
+linkTitle: 'System roles'
 weight: 22
+description: 'This guide explains how to use IAM system roles to configure user rights in CVAT.'
 ---
 
-<!--lint disable heading-style-->
+## Open Policy Agent
+
+CVAT system roles are based on the OPA microservice having [REST API](https://www.openpolicyagent.org/docs/latest/rest-api/).
+OPA is the Policy Decision Point (PDP), and it makes decisions, and CVAT is the Policy Enforcement Point (PEP),
+and enforces these decisions by providing information about requested resources or responding with an error.
+
+OPA provides a high-level declarative language that lets you specify the policy as code and simple APIs to offload
+policy decision-making from your software. CVAT controls what queries look like and implements policies to handle them.
+After a query is processed by OPA in accordance with implemented policies, OPA replies CVAT with its decision.
 
 ## System roles
+
+In the {{< repolink text="CVAT repository" path="/cvat/apps/iam/rules/" >}} for each resource there is a CSV file
+which describes all permissions in a simple and readable form.
+For example, the {{< repolink text="users.csv" path="/cvat/apps/iam/rules/users.csv" >}} file describes permissions
+for working with information about users. Every line in the file is a primitive rule which tells us who has rights
+to perform a specific action.
+
+{{< get-csv url="../../cvat/cvat/apps/iam/rules/users.csv" >}}
+
+All CSV files which describe permissions have the same set of columns:
+
+- `Scope` is the action which is performed on the resource. For example, `list` - get the list of users,
+  `update` - change information about a user, `view` - get information about a user and so on.
+
+- `Resource` describes the object on which the action is performed.
+
+- `Context` can take one of two values: `sandbox` or `organization`. An object is in the `sandbox`
+  if it is created outside of any `organization`. In theory it is possible to make an object in the `sandbox` visible
+  for other users but let's skip these details. An `organization` can have users with different roles and resources.
+  Resources are shared between members of the `organization`, but each member has permissions in accordance with their
+  role and ownership. If a user creates an object inside an `organization`, he/she delegates some rights for the object
+  to members with maintainer and owner roles in the `organization`.
+
+- `Ownership` describes how the user and the specific resource are connected together.
+  For example, `N/A` value means that the property isn't applicable for the query.
+  Some possible values can be self, owner, assignee, etc.
+  None value means that the user who is making the query doesn't have any relationships with the resource.
+
+- `Limit` covers constraints for the query. They can look not user-friendly in the table above to make
+  it easy for the code generation. This will probably be solved in future releases. Typical constrains are the number
+  of tasks and projects which a regular user can create.
+
+- `Method` and URL contain data for information purposes only and are not used.
+  They help to connect rules with the REST API. If a user makes a GET /api/users/1 call,
+  it is easy to locate corresponding permissions in the table. Thus, the scope is view,
+  the resource is user, and the context is sandbox.
+
+- `Privilege` corresponds to the group for the current user with the maximum level of permissions.
+  It can be empty if the user doesn't belong to any groups or equal to worker, user, business, or admin.
+  The primary idea is to delimit the fundamental rights of the user on the platform.
+  For example, users with the privilege less than or equal to worker cannot create tasks and projects.
+  At the same time a user with the maximum privilege admin doesn't have any restrictions.
+
+- `Membership` is the user's role inside the organization like worker, supervisor, maintainer, or owner.
+  The column makes sense only if a request is made in the context of an organization and allows
+  to delimit access to resources of the organization.
+  For example, if a user has the maintainer role in an organization,
+  but the privilege is worker, he/she will be able to see all resources in the organization
+  but not be able to create tasks and projects in the organization.
+
+If somebody needs to change the default behavior,
+it is possible to modify the policies defined in `.rego` files and restart the OPA microservice.

site/layouts/shortcodes/get-csv.html

@@ -0,0 +1,31 @@
+{{ $url := .Get "url" }}
+{{ $sep := .Get "sep" | default "," }}
+{{ if $csv := getCSV $sep $url }}
+  <table>
+    <thead>
+      <tr>
+      {{ range $i, $r := $csv }}
+        {{ if eq $i 0 }}
+          {{ range $index, $row := $r }}
+            <th>{{ $row }}</th>
+          {{ end }}
+        {{ end }}
+      {{ end }}
+      </tr>
+    </thead>
+    <tbody>
+      {{ range $i, $r := $csv }}
+        {{ if ne $i 0 }}
+          <tr>
+            {{ $l := sub (len $r) 1 }}
+            {{ range $n := (seq 0 $l) }}
+              <td>{{ index $r $n }}</td>
+            {{ end }}
+          </tr>
+        {{ end }}
+      {{ end }}
+    </tbody>
+  </table>
+{{ else }}
+  <h5 style="color: red">! URL "{{ $url }}" not found</h5>
+{{ end }}

site/layouts/shortcodes/repolink.html

@@ -0,0 +1,7 @@
+{{ $text := .Get "text" | default "this is GitHub" }}
+{{ $path := .Get "path" | default "/" }}
+{{ $icon := .Get "icon" | default "false" }}
+{{ $ver := .Site.Params.versions.version | default "develop"}}
+{{ $repolink := .Site.Params.github_repo }}
+<a href="{{ $repolink }}{{ if eq (substr $path -1) "/" }}/tree/{{ else }}/blob/{{ end }}{{ $ver }}{{ $path }}">{{ $text }}
+{{if eq $icon "true" }}<i class="fab fa-github"></i>{{ end }}</a>