feat docs: clean up docs for userver installation

commit_hash:7e5fa705129010e24682db14b086e6dad0e0ea69

Author: Anton3

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

@@ -13,7 +13,7 @@ userver-create-service [--grpc] [--mongo] [--postgresql] myservice
 
 This will create `myservice` dir, relative to the current working directory.
 
-If the command above is not found, see @ref service_templates.
+If the command above is not found, see @ref service_templates_bootstrap.
 
 To use additional userver libraries later, see @ref service_templates_libraries.
 
@@ -27,10 +27,11 @@ If the tests fail and you see messages like "No XXX installation found. Install
 installed in the environment you are running tests. Do not hesitate to install the missing database servers, like
 PostgreSQL, MongoDB and others.
 
-4\. To get a feel for how the service runs without needing to set up full production environment, run:
+4\. To get a feel for how the service runs without needing to set up full production environment,
+run in the service project root:
 
 ```shell
-myservice$ make start-debug
+make start-debug
 ```
 
 Wait until the service starts, then try to send a request.
@@ -46,10 +47,10 @@ The answer should be something like this:
 Hello, userver!
 ```
 
-5\. (Optional) Add the service project to Git:
+5\. (Optional) Add the service project to Git, run in the project root:
 
 ```shell
-myservice$ git init && git add . && git commit -m "Initial commit"
+git init && git add . && git commit -m "Initial commit"
 ```
 
 Push it to GitHub
@@ -59,39 +60,34 @@ There are preconfigured GitHub CI checks that run ctest tests.
 
 Now you are ready for fast and comfortable creation of C++ microservices, services and utilities!
 
-## Quick start for beginners (old way, pre userver 2.8)
+@anchor service_templates
+## Service templates for userver based services
 
-@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.
+@anchor service_templates_bootstrap
+### Obtaining the service template scripts
 
-1\. Press the "Use this template" button at the top right of the appropriate service template repo page:
+`userver-create-service` is available right away if you have userver @ref userver_install "installed".
 
-| 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    |
+If you use @ref devcontainers "Dev Containers", or if you @ref userver_cpm "use CPM to download userver",
+run this script to get `userver-create-service` command:
 
-2\. Clone the service:
+* Linux, macOS, BSD: @ref service-template/userver-create-service.sh
+* Windows: @ref service-template/userver-create-service.bat
 
-```shell
-git clone https://github.com/your-username/your-service.git && cd your-service
-```
+In the script, replace `vMAJOR.MINOR` with the actual userver version, or use `develop` to get bleeding-edge features
+at your own risk.
+
+---
 
-3\. Give a proper name to your service and replace all the occurrences of "*service_template" string with that name:
+If you are planning to build userver as a subdirectory (not recommended generally),
+you can temporarily add userver scripts directory to `PATH` to bring the command into scope:
 
 ```shell
-find . -not -path "./third_party/*" -not -path ".git/*" -not -path './build-*' -type f | xargs sed -i 's/service_template/YOUR_SERVICE_NAME/g'
+export PATH=/path/to/userver/scripts:$PATH
 ```
 
-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
+@anchor service_templates_run
+### Creating a new service project
 
 To create a new service project, run:
 
@@ -103,40 +99,21 @@ userver-create-service [--grpc] [--mongo] [--postgresql] myservice
 * service name will be the last segment of the path;
 * without feature flags, the service only has some stubs for HTTP handlers.
 
-If you use @ref devcontainers "Dev Containers", or if you @ref userver_cpm "use CPM to download userver",
-run this script to get `userver-create-service` command:
-
-* Linux, macOS, BSD: @ref service-template/userver-create-service.sh
-* Windows: @ref service-template/userver-create-service.bat
-
-In the script, replace `vMAJOR.MINOR` with the actual userver version, or use `develop` to get bleeding-edge features
-at your own risk.
-
-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 [--grpc] [--mongo] [--postgresql] myservice
-```
-
-You'll need to @ref ways_to_get_userver "get userver" before proceeding with local development.
-
 More information on the project directory structure can be found
 @ref scripts/docs/en/userver/tutorial/hello_service.md "here".
 
 @anchor service_templates_libraries
 ### Using additional userver libraries in service templates
 
-The service templates allow to kickstart the development of your production-ready service,
-but there can't be a repo for each and every combination of userver libraries.
-To use additional userver libraries, e.g. `userver::grpc`, add to the root `CMakeLists.txt`:
+To use additional userver libraries, e.g. `userver::kafka`, add to the root `CMakeLists.txt`:
 
 ```cmake
-find_package(userver COMPONENTS core grpc QUIET)
+find_package(userver COMPONENTS core kafka QUIET)
 ```
 
 Then add the corresponding option to @ref service_templates_presets "cmake presets",
 e.g. `"USERVER_FEATURE_GRPC": "ON"`.
+(This allows to use @ref userver_cpm "CPM" with the service project.)
 
 @see @ref userver_libraries
 
@@ -264,8 +241,8 @@ Some advice:
 userver itself can be downloaded and built using CPM.
 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.
+`download_userver()` just forwards its arguments to `CPMAddPackage` with some defaults,
+so you can pin userver `VERSION` or `GIT_TAG` for reproducible builds.
 
 When acquiring userver via CPM, you first need to install build dependencies. There are options:
 
@@ -491,7 +468,7 @@ userver framework.
 
 You can start with @ref service_templates "service template".
 
-If there a need to update the userver in the VM do the following:
+If there is a need to update userver in the VM, do the following:
 
 ```bash
 sudo apt remove libuserver-*
@@ -502,22 +479,12 @@ sudo git pull
 sudo ./scripts/build_and_install_all.sh
 ```
 
-## PGO (clang)
-
-PGO compilation consists of 2 compilation stages: profile collecting and compilation with PGO.
-You can use PGO compilation doing the following steps:
-
-1) configure userver AND your service with cmake option `-DUSERVER_PGO_GENERATE=ON`, compile the service;
-2) run the resulting binary under the production-like workload to collect profile;
-3) run llvm-profdata to convert profraw profile data format into profdata:
-   ```sh
-   llvm-profdata merge -output=code.profdata default.profraw
-   ```
-4) configure userver AND your service with cmake option `-DUSERVER_PGO_USE=<path_to_profdata>`, compile the service.
-
-The resulting binary should be 2-15% faster than without PGO, depending on the code and workload.
-
-@see @ref cmake_options
+@cond
+Guideline for documentation authors:
+* this page is the main tutorial for getting from zero to building a basic service project as soon as possible;
+* for local build dependencies, use dependencies.md;
+* for advanced build flags, use options.md.
+@endcond
 
 ----------