New Robusta Docs (#840)

Major rewrite and improvements to Robusta docs.

Author: aantn

CODING-CONVENTIONS.md

@@ -0,0 +1,41 @@
+# Coding Conventions
+
+The following guidelines apply to code contributions to the Robusta engine itself.
+
+## Formatting
+
+Robusta uses [Black](https://github.com/psf/black) and [ISort](https://pycqa.github.io/isort/) to automatically format code. Please set up Black prior so that all your contributions to Robusta will be formatted properly.
+
+For instructions on using those tools with your IDE, see:
+
+- [Black and ISort for VSCode](https://cereblanco.medium.com/setup-black-and-isort-in-vscode-514804590bf9)
+- [Black and ISort for PyCharm](https://johschmidt42.medium.com/automate-linting-formatting-in-pycharm-with-your-favourite-tools-de03e856ee17)
+
+## Linting
+
+Robusta uses [Flake8](https://flake8.pycqa.org/en/latest/) and [PyRight](https://github.com/microsoft/pyright) for code linting and type checking. Please set up Flake8 and PyRight prior so that all your contributions to Robusta will be linted properly.
+
+For instructions on using Flake8 and PyRight tools with VSCode:
+
+- [Flake8 for VSCode](https://code.visualstudio.com/docs/python/linting)
+- [PyRight for VSCode](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
+
+For instructions on using Flake8 and PyRight tools with PyCharm, see:
+
+- [Installing third-party tools in PyCharm](https://www.jetbrains.com/help/pycharm/configuring-third-party-tools.html#remote-ext-tools)
+
+## Pre-Commit Hooks
+
+Robusta uses [pre-commit](https://pre-commit.com/) to run Black, ISort, Flake8 and PyRight (and some other minor hooks) before each commit.
+
+To do so, install Robusta's dependencies with `cd src/ && poetry install` and then install the hook by running `pre-commit install`
+
+## Data classes
+
+Use `pydantic.BaseModel` instead of Python `dataclasses` when possible. Pydantic performs data validation whereas Python `dataclasses` just reduce boilerplate code like defining `__init__()`
+
+## Imports
+
+Use absolute imports whenever possible. For example, instead of `from . import foo`, use `from robusta import foo`
+
+To help with that, pre-commit hook will automatically fix relative imports to absolute imports.

CONTRIBUTING.md

@@ -1,7 +1,8 @@
 ## Contributing
-Any contribution is most welcome, fork the project, make changes and create a PR. We can't wait to review and merge your PR's!
+Contributions are welcome. Fork the project, make changes and create a PR. We can't wait to review and merge.
 
-* [Coding Conventions](https://docs.robusta.dev/master/developer-guide/platform/coding-conventions.html#formatting-and-coding-conventions)
-* [Core platform contributions](https://docs.robusta.dev/master/developer-guide/platform/dev-setup.html)
-* [Documentation contributions](https://docs.robusta.dev/master/developer-guide/platform/docs-contributions.html)
+* [Coding Conventions](./CODING-CONVENTIONS.md)
+* [Implementing Sinks](https://docs.robusta.dev/master/configuration/sinks/sinks-development.html)
+* [Implementing Actions](https://docs.robusta.dev/master/playbook-reference/actions/develop-actions/index.html)
+* [Improving the Docs](https://docs.robusta.dev/master/docs-contributions.html)
 * [Issue/Feature](https://github.com/robusta-dev/robusta/issues)

README.md

@@ -49,8 +49,7 @@ Robusta also supports alert-remediations:
 
 ![](./docs/images/alert_on_hpa_reached_limit1.png)
 
-[Over 50 types of automations and enrichments are built-in »](https://docs.robusta.dev/master/catalog/actions/index.html)
-
+[Over 50 types of automations and enrichments are built-in »](https://docs.robusta.dev/master/playbook-reference/actions/index.html
 <p align="right">(<a href="#top">back to top</a>)</p>
 
 ## 📒 Installing Robusta
@@ -72,17 +71,17 @@ helm repo add robusta https://robusta-charts.storage.googleapis.com && helm repo
 helm install robusta robusta/robusta -f ./generated_values.yaml
 ```
 
-[Detailed instructions »](https://docs.robusta.dev/master/installation.html)
+[Detailed instructions »](https://docs.robusta.dev/master/getting-started/installation.html)
 
 <!-- <p align="right">(<a href="#top">back to top</a>)</p> -->
 
 ## 📝 Documentation
 Interested? Learn more about Robusta
 
-* [Architecture](https://docs.robusta.dev/master/architecture.html)
-* [Upgrade and Uninstall](https://docs.robusta.dev/master/upgrade.html)
-* [Configuration Guide](https://docs.robusta.dev/master/user-guide/configuration.html)
-* [Triggers](https://docs.robusta.dev/master/catalog/triggers/index.html)
+* [Architecture](https://docs.robusta.dev/master/how-it-works/architecture.html)
+* [Upgrade and Uninstall](https://docs.robusta.dev/master/setup-robusta/upgrade.html)
+* [Configuration Guide](https://docs.robusta.dev/master/configuration/index.html)
+* [Triggers](https://docs.robusta.dev/master/playbook-reference/triggers/index.html)
 
 [Full documentation »](https://docs.robusta.dev/master/index.html)
 <p align="right">(<a href="#top">back to top</a>)</p>

docs.Dockerfile

@@ -0,0 +1,19 @@
+# docker build -t docs -f docs.Dockerfile .
+# docker run -it --rm -p 8000:8000 -v ${PWD}:/robusta docs
+FROM python:3.9
+
+RUN curl -s https://deb.nodesource.com/setup_16.x | bash
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends nodejs  \
+    && pip3 install --no-cache-dir --upgrade pip \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN curl -sSL https://install.python-poetry.org | python3 -
+RUN mv /root/.local/bin/poetry /usr/local/bin
+WORKDIR /robusta
+RUN poetry config virtualenvs.create false
+RUN pip install -U robusta-cli --no-cache
+COPY . /robusta/
+RUN poetry install --extras "all"
+
+CMD ["./docs_autobuild.sh", "--host 0.0.0.0"]

docs/_ext/autorobusta.py

@@ -85,6 +85,8 @@ def __document_fields(cls, fields: List[ModelField], show_code: bool, show_optio
         for field in fields:
             desc = sphinx.addnodes.desc()
             node.append(desc)
+            desc["domain"] = "robusta"
+            desc["objtype"] = "model"
             desc.extend(cls.__document_field_signature(field, show_optionality))
             desc.extend(cls.__document_field_content(field, show_code, show_optionality))
 
@@ -114,7 +116,10 @@ def __document_field_content(cls, field: ModelField, show_code: bool, show_optio
         content = sphinx.addnodes.desc_content()
 
         if field.field_info.description:
-            content.append(nodes.paragraph(text=field.field_info.description))
+            for line in field.field_info.description.splitlines():
+                if line == "|":
+                    line = "\n"
+                content.append(nodes.paragraph(text=line))
 
         if show_code:
             content.extend(cls.__document_field_example(field))
@@ -335,24 +340,10 @@ def __get_ref_for_trigger(trigger_name):
 
     @classmethod
     def __get_triggers(cls, supported_triggers: List[str], recommended_trigger: Optional[str]):
-        if ExamplesGenerator.SUBTRIGGER_MARKER in supported_triggers:
-            has_subtriggers = True
-            supported_triggers.remove(ExamplesGenerator.SUBTRIGGER_MARKER)
-        else:
-            has_subtriggers = False
-
         if recommended_trigger is not None and recommended_trigger not in supported_triggers:
             supported_triggers.insert(0, recommended_trigger)
 
         rst = [f"* :ref:`{t} <{cls.__get_ref_for_trigger(t)}>`" for t in supported_triggers]
-        if has_subtriggers:
-            rst.extend(
-                [
-                    "",
-                    "Or any other inheriting trigger. See :ref:`Trigger-Action Compatibility` for details",
-                    "",
-                ]
-            )
         return rst
 
     def __get_description(self, action_definition: Action):

docs/_static/analytics.js

@@ -2,11 +2,11 @@
 
 // noinspection DuplicatedCode
 function setupCopyListener() {
-  let codeCells = document.querySelectorAll("pre[id^=codecell]");
+  let codeCells = document.querySelectorAll("code");
   codeCells.forEach(element => element.addEventListener('copy', (event) => {
     reportCopy(element);
   }));
-  let copyButtons = document.querySelectorAll("button[data-clipboard-target*=codecell]");
+  let copyButtons = document.querySelectorAll("button[data-clipboard-target*=code]");
   copyButtons.forEach(element => element.addEventListener('click', (event) => {
     reportCopy(element);
   }));
@@ -15,11 +15,8 @@ function setupCopyListener() {
 function trackPageViewEvent() {
   const pageUrl = window.location.href;
   trackEvent('DocsPageview', {'pageUrl': pageUrl});
-  if (pageUrl.endsWith('/installation.html')) {
-    trackEvent('InstallationPageview', {'pageUrl': pageUrl});
-  }
-  if (pageUrl.endsWith('/argocd-installation.html')) {
-    trackEvent('ArgoCDInstallationPageview', {'pageUrl': pageUrl});
+  if (pageUrl.includes('setup-robusta')) {
+    trackEvent('NewInstallationPageview', {'pageUrl': pageUrl});
   }
 }
 
@@ -38,8 +35,9 @@ function reportCopy(baseElement) {
     const path = window.location.pathname;
     const page = path.split("/").pop();
     if (page && page.endsWith('html')) {
-      trackEvent('copied from a codeblock on: ' + page)
+      trackEvent('copied from a codeblock in the docs');
+      trackEvent('copied from a codeblock on: ' + page);
     }
-    trackEvent('copied from codeblock: ' + id_element.getAttribute('id'))
+    trackEvent('copied from codeblock: ' + id_element.getAttribute('id'));
   }
 }