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/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/tooling/index.md b/kb/tooling/index.md new file mode 100644 index 000000000..b36917a8f --- /dev/null +++ b/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. diff --git a/kb/tooling/task_commands.md b/kb/tooling/task_commands.md new file mode 100644 index 000000000..bd7697999 --- /dev/null +++ b/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 +``` + + +### 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 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.