From f1f5438a3dc80e2fbe531d062a23aa8b21948411 Mon Sep 17 00:00:00 2001 From: Grigory Statsenko Date: Thu, 16 Nov 2023 14:02:23 +0100 Subject: [PATCH 1/3] Knowledge Base Begins --- .gitignore | 1 + README.md | 41 +++++++---------------------------- kb/index.md | 6 ++++++ kb/tooling/index.md | 7 ++++++ kb/tooling/task_commands.md | 43 +++++++++++++++++++++++++++++++++++++ 5 files changed, 65 insertions(+), 33 deletions(-) create mode 100644 kb/index.md create mode 100644 kb/tooling/index.md create mode 100644 kb/tooling/task_commands.md diff --git a/.gitignore b/.gitignore index 1ab2f3221..43c6d713b 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ ci_artifacts .DS_Store artifacts Taskfile.yml +.obsidian diff --git a/README.md b/README.md index 966a18acd..f001b2204 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,15 @@ -## Management tasks +# datalens-backend -Running tasks: -``` -task -``` +## 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. diff --git a/kb/index.md b/kb/index.md new file mode 100644 index 000000000..4d64a2fb6 --- /dev/null +++ b/kb/index.md @@ -0,0 +1,6 @@ +# Datalens Backend Knowledge Base + +Welcome to the KB! + +See: +- [Repository tooling](tooling/index.md) diff --git a/kb/tooling/index.md b/kb/tooling/index.md new file mode 100644 index 000000000..5c5870602 --- /dev/null +++ b/kb/tooling/index.md @@ -0,0 +1,7 @@ +# 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. +- [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. diff --git a/kb/tooling/task_commands.md b/kb/tooling/task_commands.md new file mode 100644 index 000000000..7c65a2936 --- /dev/null +++ b/kb/tooling/task_commands.md @@ -0,0 +1,43 @@ +## Management tasks + +These commands require the ``taskfile`` tool. See [this page](https://taskfile.dev/installation/) +for installation options. + +Running tasks: +``` +task +``` + + +### Environment (`env:`) + +- `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:`) + +- `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 From fe33229ceea85f8e835f16cc611ca5fddbcc6f6a Mon Sep 17 00:00:00 2001 From: Grigory Statsenko Date: Fri, 17 Nov 2023 13:04:38 +0100 Subject: [PATCH 2/3] Minor fixes for KB initial commit --- kb/tooling/index.md | 5 +++-- kb/tooling/task_commands.md | 6 +++++- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/kb/tooling/index.md b/kb/tooling/index.md index 5c5870602..b36917a8f 100644 --- a/kb/tooling/index.md +++ b/kb/tooling/index.md @@ -3,5 +3,6 @@ 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. -- [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. +- 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. diff --git a/kb/tooling/task_commands.md b/kb/tooling/task_commands.md index 7c65a2936..bd7697999 100644 --- a/kb/tooling/task_commands.md +++ b/kb/tooling/task_commands.md @@ -11,6 +11,8 @@ task ### 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`: @@ -21,6 +23,8 @@ task ### Generation (`gen:`) +Generating files to be used from the code. + - `task gen:antlr`: (Re-)generate ANTLR code files for formula - `task gen:i18n-po`: @@ -31,7 +35,7 @@ task ### Code quality (`cq:`) -Experimental tasks to check and fix source files. +Checking and fixing source files. - `task cq:fix_changed`: Apply all auto-fixes From 75fc2891bb48e909a5c1c310c7d8f49608e9483d Mon Sep 17 00:00:00 2001 From: Grigory Statsenko Date: Fri, 17 Nov 2023 13:20:14 +0100 Subject: [PATCH 3/3] Some more minor fixes for KB initial commit --- kb/test_embeds.md | 15 +++++++++++++++ kb/using_kb.md | 26 ++++++++++++++++++++++++++ 2 files changed, 41 insertions(+) create mode 100644 kb/test_embeds.md create mode 100644 kb/using_kb.md diff --git a/kb/test_embeds.md b/kb/test_embeds.md new file mode 100644 index 000000000..32e1f21b9 --- /dev/null +++ b/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 +``` diff --git a/kb/using_kb.md b/kb/using_kb.md new file mode 100644 index 000000000..a160ec945 --- /dev/null +++ b/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.