fix docs: clean up userver-create-service docs

commit_hash:692a2992eb562454f4b530618dcee9a41560ba84

Author: Anton3

.mapping.json

@@ -3742,6 +3742,7 @@
   "scripts/docs/en/userver/tutorial/websocket_service.md":"taxi/uservices/userver/scripts/docs/en/userver/tutorial/websocket_service.md",
   "scripts/docs/en/userver/ydb.md":"taxi/uservices/userver/scripts/docs/en/userver/ydb.md",
   "scripts/docs/examples/service-template/CMakeUserPresets.json.example":"taxi/uservices/userver/scripts/docs/examples/service-template/CMakeUserPresets.json.example",
+  "scripts/docs/examples/service-template/userver-create-service.sh":"taxi/uservices/userver/scripts/docs/examples/service-template/userver-create-service.sh",
   "scripts/docs/fontello/README.txt":"taxi/uservices/userver/scripts/docs/fontello/README.txt",
   "scripts/docs/fontello/config.json":"taxi/uservices/userver/scripts/docs/fontello/config.json",
   "scripts/docs/fontello/css/animation.css":"taxi/uservices/userver/scripts/docs/fontello/css/animation.css",
@@ -3878,6 +3879,7 @@
   "service_template/.gitignore":"taxi/uservices/userver/service_template/.gitignore",
   "service_template/.vscode/README.md":"taxi/uservices/userver/service_template/.vscode/README.md",
   "service_template/.vscode/c_cpp_properties.json":"taxi/uservices/userver/service_template/.vscode/c_cpp_properties.json",
+  "service_template/.vscode/settings.json":"taxi/uservices/userver/service_template/.vscode/settings.json",
   "service_template/CMakeLists.txt":"taxi/uservices/userver/service_template/CMakeLists.txt",
   "service_template/CMakePresets.json":"taxi/uservices/userver/service_template/CMakePresets.json",
   "service_template/Makefile":"taxi/uservices/userver/service_template/Makefile",

scripts/docs/en/userver/build/build.md

@@ -5,105 +5,108 @@
 
 1\. @ref ways_to_get_userver "Get userver".
 
-2\. Create new service with the following command (if you installed userver system-wide):
+2\. Create a new service project with the following command:
 
 ```shell
-userver-create-service myservice
+userver-create-service [--grpc] [--mongo] [--postgresql] myservice
 ```
 
-If you installed userver via CPM or as a git repository, call script from userver directory:
-```shell
-userver/scripts/userver-create-service myservice
-```
+This will create `myservice` dir, relative to the current working directory.
+
+If you did not install userver system-wide and the command above is not found, see @ref service_templates.
+
+To use additional userver libraries later, see @ref service_templates_libraries.
 
-If you want to enable gRPC, postgresql, or mongo in your service, use the following flags:
+3\. Build and test your service. Run in the service project root:
 
 ```shell
-userver-create-service --grpc --mongo --postgresql myservice
+make build-debug && \
+make test-debug
 ```
 
-3\. Build and test your service. Run in the service repo root:
+4\. To get a feel for how the service runs without needing to set up full production environment, run:
 
 ```shell
-make build-release && \
-make test-release
+myservice$ make start-debug
 ```
 
-Now you are ready for fast and comfortable creation of C++ microservices, services and utilities!
-
+Wait until the service starts, then try to send a request.
 
-## Quick start for beginners (old way)
+```shell
+curl http://127.0.0.1:8080/hello?name=userver
+```
 
-1\. Press the "Use this template" button at the top right of the
-[GitHub template page](https://github.com/userver-framework/service_template).
+The answer should be something like this:
 
-@warning [service_template](https://github.com/userver-framework/service_template) has no databases and uses HTTP.
-If you need gRPC or a database, please use other @ref service_templates "templates".
+```shell
+> curl http://127.0.0.1:8080/hello?name=userver
+Hello, userver!
+```
 
-2\. Clone the service:
+5\. (Optional) Add the service project to Git:
 
 ```shell
-git clone https://github.com/your-username/your-service.git && cd your-service
+myservice$ git init && git add . && git commit -m "Initial commit"
 ```
 
-3\. @ref ways_to_get_userver "Get userver".
+Push it to GitHub
+(see [its documentation](https://docs.github.com/en/migrations/importing-source-code/using-the-command-line-to-import-source-code/adding-locally-hosted-code-to-github#adding-a-local-repository-to-github-using-git)).
 
-4\. Build and start your service. Run in the service repo root:
+There are preconfigured GitHub CI checks that run ctest tests.
 
-```shell
-make build-release && \
-make start-release
-```
+Now you are ready for fast and comfortable creation of C++ microservices, services and utilities!
 
-During the build, you can make a coffee break until approximately the following output appears:
+## Quick start for beginners (old way, pre userver 2.8)
 
-```shell
-====================================================================================================
-Started service at http://localhost:8080/, configured monitor URL is http://localhost:-1/
-====================================================================================================
+@warning Service template repositories are deprecated, because possible sets of userver libraries to include cause
+an exponential growth in the number of wanted repositories. For userver 2.9 and later, use
+the @ref quick_start_for_beginners "service project generator script" instead.
 
-PASSED
-[service-runner] Service started, use C-c to terminate
-INFO     <userver> Server is started
-...
-DEBUG    <userver> Accepted connection #2/32768
-DEBUG    <userver> Incoming connection from ::ffff:127.0.0.1, fd 43
+1\. Press the "Use this template" button at the top right of the appropriate service template repo page:
 
-```
+| Link                                                             | Contains               |
+|------------------------------------------------------------------|------------------------|
+| https://github.com/userver-framework/service_template            | HTTP                   |
+| https://github.com/userver-framework/pg_service_template         | HTTP, PostgreSQL       |
+| https://github.com/userver-framework/pg_grpc_service_template    | HTTP, PostgreSQL, gRPC |
+| https://github.com/userver-framework/mongo_grpc_service_template | HTTP, MongoDB, gRPC    |
 
-5\. Try to send a request.
+2\. Clone the service:
 
 ```shell
-curl http://127.0.0.1:8080/hello?name=userver
+git clone https://github.com/your-username/your-service.git && cd your-service
 ```
 
-The answer should be something like this:
+3\. Give a proper name to your service and replace all the occurrences of "*service_template" string with that name:
 
 ```shell
-> curl http://127.0.0.1:8080/hello?name=userver
-Hello, userver!
+find . -not -path "./third_party/*" -not -path ".git/*" -not -path './build-*' -type f | xargs sed -i 's/service_template/YOUR_SERVICE_NAME/g'
 ```
 
-Now you are ready for fast and comfortable creation of C++ microservices, services and utilities!
+4\. @ref ways_to_get_userver "Get userver".
+
+5\. Build and test the service, see steps 3-4 from the @ref quick_start_for_beginners "updated instruction above".
 
 @anchor service_templates
 ## Service templates for userver based services
 
-There are ready to use service templates at GitHub:
+To create a new service project, run:
 
-| Link                                                             | Contains               |
-|------------------------------------------------------------------|------------------------|
-| https://github.com/userver-framework/service_template            | HTTP                   |
-| https://github.com/userver-framework/pg_service_template         | HTTP, PostgreSQL       |
-| https://github.com/userver-framework/pg_grpc_service_template    | HTTP, PostgreSQL, gRPC |
-| https://github.com/userver-framework/mongo_grpc_service_template | HTTP, MongoDB, gRPC    |
+```shell
+userver-create-service [--grpc] [--mongo] [--postgresql] myservice
+```
 
-To create a service:
+* Project directory will be `myservice`, relative to the current working directory;
+* service name will be the last segment of the path;
+* even without feature flags, the service only has some stubs for HTTP handlers.
 
-1. Press the "Use this template" button at the top right of the GitHub template page
-2. Clone the service `git clone your-service-repo && cd your-service-repo`
-3. Give a proper name to your service and replace all the occurrences of "*service_template" string with that name.
-4. Feel free to tweak, adjust or fully rewrite the source code of your service.
+If instead of installing userver you are planning to build userver as a subdirectory, call the script from userver directory:
+
+```shell
+path/to/userver/scripts/userver-create-service myservice
+```
+
+If you use CPM to download userver, see @ref userver_cpm "CPM section".
 
 You'll need to @ref ways_to_get_userver "get userver" before proceeding with local development.
 
@@ -246,9 +249,7 @@ Some advice:
 ### Downloading userver using CPM
 
 userver itself can be downloaded and built using CPM.
-In fact, this is what
-[download_userver()](https://github.com/userver-framework/service_template/blob/develop/cmake/DownloadUserver.cmake)
-function does in @ref service_templates "service templates" by default.
+In fact, this is what `download_userver()` function does in @ref service_templates "service templates" by default.
 
 `download_userver()` just calls `CPMAddPackage` with some defaults, so you can pin userver `VERSION` or `GIT_TAG`
 for reproducible builds.
@@ -258,6 +259,10 @@ When acquiring userver via CPM, you first need to install build dependencies. Th
 * install @ref scripts/docs/en/userver/build/dependencies.md "build dependencies"
 * or use base image of @ref docker_with_ubuntu_22_04
 
+To use a @ref service_templates "service template" with CPM, run this script to get `userver-create-service` command:
+
+@ref service-template/userver-create-service.sh
+
 Make sure to @ref service_templates_presets "enable" the CMake options to build userver libraries you need,
 then link to those libraries.
 
@@ -480,3 +485,4 @@ The resulting binary should be 2-15% faster than without PGO, depending on the c
 @htmlonly </div> @endhtmlonly
 
 @example service-template/CMakeUserPresets.json.example
+@example service-template/userver-create-service.sh

scripts/docs/en/userver/supported_platforms.md

@@ -30,17 +30,21 @@ organization page contains multiple repositories, including:
 * [uservice-dynconf](https://github.com/userver-framework/uservice-dynconf) -
   the service to control dynamic configs of the other userver-based services.
 
-Also there are several legacy template services (use userver-create-service script instead):
+Also, there are several legacy template services
+(use @ref quick_start_for_beginners "userver-create-service" script instead):
 
 * [service_template](https://github.com/userver-framework/service_template) -
-  template of a C++ service that uses userver framework with ready-to-user
-  build, test and CI scripts. 
+  template of a C++ service that uses userver framework with ready-to-use
+  build, test and CI scripts.
 * [pg_service_template](https://github.com/userver-framework/pg_service_template) -
-  template of a C++ service that uses userver framework with ready-to-user PostgreSQL database,
-  build, test and CI scripts. 
+  template of a C++ service that uses userver framework with ready-to-use PostgreSQL database,
+  build, test and CI scripts.
 * [pg_grpc_service_template](https://github.com/userver-framework/pg_grpc_service_template) -
-  template of a C++ service that uses userver framework with ready-to-user PostgreSQL database, gRPC server,
-  build, test and CI scripts. 
+  template of a C++ service that uses userver framework with ready-to-use PostgreSQL database, gRPC server,
+  build, test and CI scripts.
+* [mongo_grpc_service_template](https://github.com/userver-framework/mongo_grpc_service_template) -
+  template of a C++ service that uses userver framework with ready-to-use Mongo database, gRPC server,
+  build, test and CI scripts.
 
 All the repositories are part of the userver framework,
 thus they support the same set of architectures, compilers, operating systems

scripts/docs/examples/service-template/userver-create-service.sh

@@ -0,0 +1,10 @@
+userver-create-service() {
+    REPO_URL="https://github.com/userver-framework/userver.git"
+    BRANCH="develop"
+    WORKDIR="/tmp/userver-create-service"
+    if [ ! -d "$WORKDIR" ]; then
+        mkdir -p "$WORKDIR"
+        git clone -q --depth 1 --branch "$REPO_URL" "$BRANCH" "$WORKDIR"
+    fi
+    "$WORKDIR/scripts/userver-create-service" "$@"
+}

scripts/userver-create-service

@@ -33,21 +33,20 @@ def parse_args():
         description='Create new C++ userver-based service')
     for feature in FEATURES:
         parser.add_argument(f'--{feature}', action='store_true')
-    parser.add_argument('service_path')
+    parser.add_argument('service_path', type=pathlib.Path)
     return parser.parse_args()
 
 
-def service_name(service_path: str) -> str:
-    return os.path.basename(os.path.normpath(service_path)).replace('-', '_')
+def service_name(service_path: pathlib.Path) -> str:
+    return service_path.resolve().name.replace('-', '_')
 
 
 def handle_file(src: pathlib.Path, dst: pathlib.Path, args) -> bool:
     orig_text = src.read_text()
     text = []
     skip = False
     for line in orig_text.splitlines():
-        line = line.replace('service_template',
-                            service_name(args.service_path))
+        line = line.replace('service_template', service_name(args.service_path))
         match_on = TEMPLATE_ON_REGEX.match(line)
         match_current = TEMPLATE_CURRENT_REGEX.match(line)
         if match_on:
@@ -74,7 +73,7 @@ def handle_file(src: pathlib.Path, dst: pathlib.Path, args) -> bool:
 def copy_tree(src: pathlib.Path, dst: pathlib.Path, args) -> None:
     for root, _, files in os.walk(src):
         dst_root = dst / pathlib.Path(root).relative_to(src)
-        os.makedirs(dst_root, exist_ok=True)
+        dst_root.mkdir(parents=True, exist_ok=True)
         dst_root_is_empty = True
 
         for file in files:
@@ -91,21 +90,20 @@ def run_ruff(src: pathlib.Path) -> None:
     try:
         subprocess.check_call(['ruff', 'format', str(src)])
     except BaseException as exc:
-        print(f'Failed to run ruff ({exc}), skipping.')
+        print(f'Warning: Failed to run ruff ({exc}), skipping.', file=sys.stderr)
 
 
-def check_dst_non_existing(service_path: str):
-    if pathlib.Path(service_path).exists():
-        print(f'Error: {service_path} directory already exists.',
-              file=sys.stderr)
+def check_dst_non_existing(service_path: pathlib.Path):
+    if service_path.exists():
+        print(f'Error: {service_path} directory already exists.', file=sys.stderr)
         sys.exit(1)
 
 
 def main() -> None:
     args = parse_args()
     check_dst_non_existing(args.service_path)
     copy_tree(template_path(), args.service_path, args)
-    run_ruff(pathlib.Path(args.service_path))
+    run_ruff(args.service_path)
 
 
 if __name__ == '__main__':

service_template/.github/workflows/ci.yml

@@ -1,3 +1,5 @@
+# NOTE: if this CI check breaks, just remove it, docker checks are enough anyway.
+
 name: CI
 
 'on':

service_template/.github/workflows/docker.yaml

@@ -10,6 +10,9 @@ name: Docker build
           - develop
           - feature/**
 
+env:
+    UBSAN_OPTIONS: print_stacktrace=1
+
 jobs:
     tests:
         runs-on: ubuntu-latest
@@ -28,10 +31,10 @@ jobs:
                     ccache-
 
           - name: Cmake
-            run: make docker-cmake-release
+            run: make docker-cmake-debug
 
           - name: Build
-            run: make docker-build-release
+            run: make docker-build-debug
 
           - name: Test
-            run: make docker-test-release
+            run: make docker-test-debug

service_template/.vscode/settings.json

@@ -0,0 +1,13 @@
+{
+  "cmake.automaticReconfigure": false,
+  "cmake.configureOnEdit":  false,
+  "cmake.configureOnOpen": false,
+  "cmake.copyCompileCommands": "${workspaceFolder}/.vscode/compile_commands.json",
+  "clangd.arguments": [
+    "--background-index",
+    "--compile-commands-dir=.vscode",
+    "--clang-tidy",
+    "--completion-style=detailed",
+    "--header-insertion=never"
+  ]
+}