Knowledge Base Begins

.gitignore

@@ -15,3 +15,4 @@ ci_artifacts
 .DS_Store
 artifacts
 Taskfile.yml
+.obsidian

README.md

@@ -1,40 +1,15 @@
-## Management tasks
+# datalens-backend
 
-Running tasks:
-```
-task <task_name>
-```
+## About
 
+This is the repository for the back-end implementation of DataLens
 
-### Environment (`env:`)
+Head over to the [Knowledge Base](kb/index.md) for documentation on this repo.
 
-- `task env:devenv`:
-  Create development/testing environment (run it from a package dir)
-- `task env:devenv-d`:
-  Create development/testing environment in detached mode (run it from a package dir)
-- `task env:ensure_venv`: Command to create virtual env for the mainrepo tools. 
-  It requires presence of .env in the mainrepo/tools.
+[Code of conduct](CODE_OF_CONDUCT.md)
 
+[Contributing](CONTRIBUTING.md)
 
-### Generation (`gen:`)
+## License
 
-- `task gen:antlr`:
-  (Re-)generate ANTLR code files for formula
-- `task gen:i18n-po`:
-  Sync/generate `.po` files for package (run it from a package dir)
-- `task gen:i18n-binaries`:
-  Generate binary `.mo` files from `.po` files for package (run it from a package dir)
-
-
-### Code quality (`cq:`)
-
-Experimental tasks to check and fix source files. 
-
-- `task cq:fix_changed`:
-  Apply all auto-fixes
-- `task cq:check_changed`:
-  Check for any non-conformity in code style/format/lint
-- `task cq:fix_dir -- {single dir}`:
-  Apply all auto-fixes to the given dir absolute path
-- `task cq:check_dir -- {single dir}`:
-  Check for any non-conformity in code style/format/lint in the given dir abs path
+`datalens-backend` is available under the Apache 2.0 license.

kb/index.md

@@ -0,0 +1,6 @@
+# Datalens Backend Knowledge Base
+
+Welcome to the KB!
+
+See:
+- [Repository tooling](tooling/index.md)

kb/test_embeds.md

@@ -0,0 +1,15 @@
+This is a file to test embedded diagrams. 
+
+
+``` plantuml
+@startuml
+digraph foo {
+  node [style=rounded]
+  node1 [shape=box]
+  node2 [fillcolor=yellow, style="rounded,filled", shape=diamond]
+  node3 [shape=record, label="{ a | b | c }"]
+
+  node1 -> node2 -> node3
+};
+@enduml
+```

kb/tooling/index.md

@@ -0,0 +1,8 @@
+# Repository Tooling
+
+This section is about the custom tooling available in this repo.
+
+- [task commands](task_commands.md) - a set of (`make`-like) shortcuts for various commands and scripts for repository management, development, testing, etc.
+- tools from `terrarium` ([README](../../terrarium/README.md)):
+  - [dl-git](../../terrarium/dl_gitmanager/README.md) - a wrapper for advanced git commands, for usage mainly in the CI workflow
+  - [dl-repo / dl-package](../../terrarium/dl_repmanager/README.md) - tools for managing and inspecting packages, their dependencies, meta-packages, etc.

kb/tooling/task_commands.md

@@ -0,0 +1,47 @@
+## Management tasks
+
+These commands require the ``taskfile`` tool. See [this page](https://taskfile.dev/installation/)
+for installation options.
+
+Running tasks:
+```
+task <task_name>
+```
+
+
+### Environment (`env:`)
+
+Working with the testing/development environment.
+
+- `task env:devenv`:
+  Create development/testing environment (run it from a package dir)
+- `task env:devenv-d`:
+  Create development/testing environment in detached mode (run it from a package dir)
+- `task env:ensure_venv`: Command to create virtual env for the mainrepo tools. 
+  It requires presence of .env in the mainrepo/tools.
+
+
+### Generation (`gen:`)
+
+Generating files to be used from the code.
+
+- `task gen:antlr`:
+  (Re-)generate ANTLR code files for formula
+- `task gen:i18n-po`:
+  Sync/generate `.po` files for package (run it from a package dir)
+- `task gen:i18n-binaries`:
+  Generate binary `.mo` files from `.po` files for package (run it from a package dir)
+
+
+### Code quality (`cq:`)
+
+Checking and fixing source files. 
+
+- `task cq:fix_changed`:
+  Apply all auto-fixes
+- `task cq:check_changed`:
+  Check for any non-conformity in code style/format/lint
+- `task cq:fix_dir -- {single dir}`:
+  Apply all auto-fixes to the given dir absolute path
+- `task cq:check_dir -- {single dir}`:
+  Check for any non-conformity in code style/format/lint in the given dir abs path

kb/using_kb.md

@@ -0,0 +1,26 @@
+# Working with the KB
+
+This KB is mostly `Markdown`, but it has embedded charts.
+These usually don't work out-of-the-box and might require a little additional configuration.
+
+To check the correect rendering of embedded charts open [this file](test_embeds.md).
+If your editor supports this, and everything is configured correctly,
+you should see a rendered charts.
+
+Here are two options you can use to work with this KB
+
+## PyCharm
+
+- Install `graphviz`.
+- Install and enable the Markdown plugin in PyCharm.
+
+In theory this should be enough, but you may find that charts give you a rendering error
+about not finding "dot".
+In this case find the `dot` executable in your system and copy it to `/opt/local/bin/dot`.
+It should work now.
+
+## Obsidian
+
+- Install the `Obsidian` app
+- Install the PlantUML plugin in Obsidian.
+  You might need to configure the path to the dot executable.