docs-reorg: refactor Install section

Author: fenekku

docs/community/code/package-development.md

@@ -16,7 +16,7 @@ editable install of the Python package:
 !!! note
 
     ``mkvirtualenv`` is a tool provided by virtualenv-wrapper to manage Python
-    virtualenvs. See [Python virtual environments](../../install/virtualenvs.md)
+    virtualenvs. See [Python virtual environments](../../reference/virtualenvs.md)
 
 ```bash
 cd ~/src/invenio-app-rdm

docs/install/build-setup-run.md

@@ -1,42 +1,45 @@
 # Build, setup and run
 
-Now, that we have created a project folder, we need to build and set up the InvenioRDM application.
+Now that we have created a project folder, we need to build and set up the InvenioRDM application.
 
-The application can be built and installed in two different ways:
+As mentioned before, the application can be built and installed in two different ways:
 
-- Local (good for developers or for customizing your instance): The application is installed locally on your machine in a Python virtual environment managed by the ``pipenv`` tool.
-- Container (good for quick preview): The application is built inside a Docker image.
+- *Local development* (good for developers or for customizing your instance): The application is installed directly on your machine in a Python [virtual environment](../reference/virtualenvs.md) managed by the ``pipenv`` tool (its services are containerized though).
+- *Containerized preview* (good for quick preview): The application is built inside a Docker image and, it, along with the services are all containerized.
 
-## For the impatient
+## Condensed version
 
 For the impatient, here are the commands to build, setup and run InvenioRDM. For clarity, we have decomposed them into individual steps in the guide below. Follow the guide below for step-by-step details:
 
-Container:
+=== "Local development"
 
-```bash
-invenio-cli containers start --lock --build --setup
-```
+    ```shell
+    # Install Python and Javascript packages
+    invenio-cli install
+    # Set up containerized database, cache, OpenSearch, etc.
+    invenio-cli services setup
+    # Serve the application locally through a development server
+    invenio-cli run
+    ```
 
-Local:
+=== "Containerized preview"
 
-```bash
-invenio-cli install
-invenio-cli services setup
-invenio-cli run
-```
+    ```shell
+    invenio-cli containers start --lock --build --setup
+    ```
 
 !!! info
-    If you run the above commands, you're all set for this section. If you like to learn more about the build process,
+    If you run the above commands, you're all set for this section. If you would like to learn more about the build process,
     then follow the steps below instead.
 
 
 ## Python dependencies
 
 First, we start by locking the Python dependencies, which ensures that you will always have the same versions of dependencies if you reinstall in the future. Locked dependencies are important for having reproducible installs.
 
-This step will normally be executed automatically by both the local and container installation options, but here we run it explicitly.
+This step is executed automatically by both the local development (under `invenio-cli install`) and containerized preview (`--lock` option) installation options, but here we run it explicitly.
 
-Let's try it:
+It's the same command for either installation option. Let's try it:
 
 ```bash
 cd my-site/
@@ -70,49 +73,43 @@ Dependencies locked successfully.
 
 A new file ``Pipfile.lock`` has now been created with the locked dependencies.
 
-Next, choose option 1 or option 2 for your preferred installation method.
+Next, follow the *local development* option or *containerized preview* option according to your preferred installation method.
 
-## Option 1: Container install
+## Local development option
 
-The container install is good for a quick preview, or if you don't want all dependencies locally. It is not good for development or for customizing your instance, as it requires you to rebuild the Docker image for every change which can be time consuming.
+The local install is good for developers or if you like to customize InvenioRDM as it avoids the waiting time for building a new Docker image. For instance, changing the layout will be much faster with a local install.
 
 ### Build
 
-For the container build, you first build the Docker application image using
-the following command:
+The local build steps involve installing all the Python dependencies into a local Python virtual environment, as well as all the Javascript dependencies. The Javascript dependencies are defined in the Python packages. This is done with the command:
 
 ```bash
-invenio-cli containers build
+invenio-cli install
 ```
 ```console
-Building images... Pull newer versions True, use cache True
-Checking if dependencies are locked.
-Dependencies are locked
-Building images...
+Installing python dependencies... Please be patient, this operation might take some time...
+Installing dependencies from Pipfile.lock (271a6d)…
+  🐍   ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ 200/200 — 00:02:00
 
 [...]
 
-Successfully built f1fc95ce1037
-Successfully tagged my-site:latest
-Images built successfully.
+Built webpack project.
+Assets and statics updated.
+Dependencies installed successfully.
 ```
 
-The command will:
+The command does the following:
 
-- Download the Docker images for the services (database, cache, search engine, etc.)
-- Build the Docker image for the InvenioRDM application using the ``Dockerfile`` in your project.
 - Install Python dependencies (according the ``Pipfile.lock``)
 - Install JavaScript dependencies
 - Build the JavaScript/CSS web assets
 
 ### Setup
 
-Once the Docker application image has been built, we need to initialize the database, the indices and so on. For this, we use again the ``containers`` command.
-
-The first time this command is run, the services will be setup correctly and the containers running them will even restart upon a reboot of your machine. If you stop and restart those containers, your data will still be there. Upon running this command again, the initial setup is skipped.
+We need to initialize the database, the indices and so on. For this, we use the services command. The first time this command is run, the services will be setup correctly and the containers running them will even restart upon a reboot of your machine. If you stop and restart those containers, your data will still be there. Upon running this command again, the initial setup is skipped.
 
 ```bash
-invenio-cli containers setup
+invenio-cli services setup
 ```
 ```console
 Making sure containers are up...
@@ -132,71 +129,83 @@ Creating indexes...
 Putting templates...
 ```
 
-The command will:
-
-- Create the database and Elasticsearch indexes.
-- Load fixtures data into InvenioRDM.
-- Create demo records.
-
 !!! tip
 
     You can skip the creation of demo records by using the ``--no-demo-data`` option (``-N`` for short):
 
+    ```shell
+    invenio-cli services setup --no-demo-data
     ```
-    invenio-cli containers setup --no-demo-data
+
+    You can forcefully redo the setup step with the ``--force`` option (``-f`` for short):
+
+    ```shell
+    invenio-cli services setup --force
     ```
 
 ### Run
 
-You can now run the application container and related services:
+You can now run the application locally:
 
 ```bash
-invenio-cli containers start
+invenio-cli run
 ```
 
-Go and explore your InvenioRDM instance at [https://127.0.0.1](https://127.0.0.1).
+Go and explore your InvenioRDM instance at [https://127.0.0.1:5000](https://127.0.0.1:5000). This is the default host and port configured in ``invenio.cfg``.
 
-!!! warning "Visit 127.0.0.1, not localhost"
-    Due to Content Security Policy (CSP) headers it is important that you visit ``127.0.0.1``, and not ``localhost`` unless you set ``INVENIO_SITE_UI_URL`` and ``INVENIO_SITE_API_URL`` to ``https://localhost`` and ``https://localhost/api`` respectively.
 
-!!! tip
-    You can provide other configuration variables by setting them as environment variables with the ``INVENIO_`` prefix.
+!!! tip "Change the host and port"
+    By default, the host is `127.0.0.1` and the port is `5000`. Pass `--host` and `--port`
+    to change them:
 
-## Option 2: Local install
+      `invenio-cli run --host 0.0.0.0 --port 443`
 
-The local install is good for developers or if you like to customize InvenioRDM as it avoids the waiting time for building a new Docker image. For instance, changing the layout will be much faster with a local install.
+    It's a development server though, so don't use it for production.
+
+!!! warning "Visit 127.0.0.1, not localhost"
+    Due to Content Security Policy (CSP) headers it is important that you use ``127.0.0.1``, and not ``localhost``.
+
+## Containerized preview option
+
+The container install is good for a quick preview, or if you don't want all dependencies locally. It is not good for development or for customizing your instance, as it requires you to rebuild the Docker image for every change which can be time consuming.
 
 ### Build
 
-The local build steps involve installing all the Python dependencies into a local Python virtual environment. This is done with the command (the virtualenv is managed by ``pipenv``):
+For the container build, you first build the Docker application image using
+the following command:
 
 ```bash
-invenio-cli install
+invenio-cli containers build
 ```
 ```console
-Installing python dependencies... Please be patient, this operation might take some time...
-Installing dependencies from Pipfile.lock (271a6d)…
-  🐍   ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ 200/200 — 00:02:00
+Building images... Pull newer versions True, use cache True
+Checking if dependencies are locked.
+Dependencies are locked
+Building images...
 
 [...]
 
-Built webpack project.
-Assets and statics updated.
-Dependencies installed successfully.
+Successfully built f1fc95ce1037
+Successfully tagged my-site:latest
+Images built successfully.
 ```
 
-Similar to the ``containers`` command, the command does the following:
+The command will:
 
+- Download the Docker images for the services (database, cache, search engine, etc.)
+- Build the Docker image for the InvenioRDM application using the ``Dockerfile`` in your project.
 - Install Python dependencies (according the ``Pipfile.lock``)
 - Install JavaScript dependencies
 - Build the JavaScript/CSS web assets
 
 ### Setup
 
-We need to initialize the database, the indices and so on. For this, we use the services command. The first time this command is run, the services will be setup correctly and the containers running them will even restart upon a reboot of your machine. If you stop and restart those containers, your data will still be there. Upon running this command again, the initial setup is skipped.
+Once the Docker application image has been built, we need to initialize the database, the indices and so on. For this, we use again the ``containers`` command.
+
+The first time this command is run, the services will be setup correctly and the containers running them will even restart upon a reboot of your machine. If you stop and restart those containers, your data will still be there. Upon running this command again, the initial setup is skipped.
 
 ```bash
-invenio-cli services setup
+invenio-cli containers setup
 ```
 ```console
 Making sure containers are up...
@@ -216,35 +225,41 @@ Creating indexes...
 Putting templates...
 ```
 
+The command will:
+
+- Create the database and Elasticsearch indexes.
+- Load fixtures data into InvenioRDM.
+- Create demo records.
+
 !!! tip
 
     You can skip the creation of demo records by using the ``--no-demo-data`` option (``-N`` for short):
 
-    ```
-    invenio-cli services setup --no-demo-data
+    ```shell
+    invenio-cli containers setup --no-demo-data
     ```
 
+    You can forcefully redo the setup step with the ``--force`` option (``-f`` for short):
+
+    ```shell
+    invenio-cli containers setup --force
+    ```
 
 ### Run
 
-You can now run the application locally:
+You can now run the application container and related services:
 
 ```bash
-invenio-cli run
+invenio-cli containers start
 ```
 
-Go and explore your InvenioRDM instance at [https://127.0.0.1:5000](https://127.0.0.1:5000). This is the default host and port configured in ``invenio.cfg``.
-
-!!! warning "Visit 127.0.0.1, not localhost"
-    Due to Content Security Policy (CSP) headers it is important that you use ``127.0.0.1``, and not ``localhost``.
-
-!!! tip "Change the host and port"
-    By default, the host is `127.0.0.1` and the port is `5000`. Pass `--host` and `--port`
-    to change them e.g.:
+Go and explore your InvenioRDM instance at [https://127.0.0.1](https://127.0.0.1).
 
-      `invenio-cli run --host 0.0.0.0 --port 443`
+!!! tip
+    You can provide other configuration variables by setting them as environment variables with the ``INVENIO_`` prefix.
 
-    It's a development server, so don't use it for production.
+!!! warning "Visit 127.0.0.1, not localhost"
+    Due to Content Security Policy (CSP) headers it is important that you visit ``127.0.0.1``, and not ``localhost`` unless you set ``INVENIO_SITE_UI_URL`` and ``INVENIO_SITE_API_URL`` to ``https://localhost`` and ``https://localhost/api`` respectively.
 
 ## Troubleshooting
 

docs/install/cli.md

@@ -1,39 +1,41 @@
-# Install CLI
+# Install the command line tool
 
-InvenioRDM comes with a CLI management tool called Invenio-CLI which is used to manage and work with your local installation.
+InvenioRDM is set up with a command line management tool, `invenio-cli`, which is used to manage and work with your local installation.
 
-You can install the Invenio CLI package named `invenio-cli`. The package is available on [PyPI](https://pypi.org/project/invenio-cli/). Use your favorite way to install a Python package:
+## Installation
 
-Via pip:
+`invenio-cli` is available on [PyPI](https://pypi.org/project/invenio-cli/). Use your favorite way to install it:
 
-```bash
-pip install invenio-cli
-```
+=== "pip"
 
-Via pipenv:
+    ```shell
+    pip install invenio-cli
+    ```
 
-```bash
-pipenv install invenio-cli
-```
+=== "uv"
 
-Via pipx:
+    ```shell
+    uv tool install invenio-cli
+    ```
 
-```bash
-pipx install invenio-cli
-```
+=== "pipx"
+
+    ```shell
+    pipx install invenio-cli
+    ```
 
-To make sure you've installed successfully:
+To make sure you've installed it successfully:
 
 ```bash
 invenio-cli --version
 ```
 
-You'll find the latest released version number on [PyPi](https://pypi.org/project/invenio-cli/).
+You'll find the latest released version number on [PyPi](https://pypi.org/project/invenio-cli/). Each new version of InvenioRDM is accompanied by a new version of `invenio-cli` if only to have it select the new version as the default when initializing a project.
 
-### Commands reference
+## Commands reference
 
 For a full reference of available commands, see the [CLI reference](../reference/cli.md)
 
 
 !!! tip "Shell tab completion"
-     Invenio-CLI has support for Shell tab completion of commands. See [Shell completion](../reference/cli.md#shell-completion).
+     `invenio-cli` has support for shell tab completion of commands. See [shell completion](../reference/cli.md#shell-completion).