PG-798 Restructured docs (#601)

PG-798 Restructure docs

* Updated README.md

* Reworked the What's in it section

* Added power number

* updated Contributing file

* Added etcd to extensions list and fixed naming

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "cSpell.words": [
+        "Quickstart"
+    ]
+}

CONTRIBUTING.md

@@ -32,6 +32,8 @@ Each version has a branch in the repository named accordingly:
 - 12
 - 13
 - 14
+- 15
+- 16
 
 The source .md files are in the ``docs`` directory. 
 
@@ -75,6 +77,7 @@ git remote add <your-repo-name> [email protected]:<your_name>/postgresql-docs.git
 git fetch origin
 git merge origin/<branch>
 ```
+
 Make sure that your local branch and the branch you merge changes from are the same. So if you are on ``11`` branch, merge changes from ``origin/11``.
 
 5. Create a separate branch for your changes
@@ -102,15 +105,15 @@ Learn more about the documentation structure in the [Repository structure](#repo
 2. We use [this Docker image](https://github.com/Percona-Lab/percona-doc-docker) to build documentation. Run the following command:
 
 ```sh
-docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md -f mkdocs-netlify.yml
+docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build
 ```
    If Docker can't find the image locally, it first downloads the image, and then runs it to build the documentation.
 
 3. Go to the ``site`` directory and open the ``index.html`` file to see the documentation.
 4. To view your changes as you make them, run the following command:
 
 ``` sh
-docker run --rm -p 8000:8000 -v $(pwd):/docs perconalab/pmm-doc-md mkdocs serve -f mkdocs-netlify.yml -a 0.0.0.0:8000
+docker run --rm -p 8000:8000 -v $(pwd):/docs perconalab/pmm-doc-md mkdocs serve -a 0.0.0.0:8000
 ```
 
 5. To create a PDF version of the documentation, run the following command:
@@ -128,13 +131,13 @@ The PDF document is in the ``site/pdf`` folder.
 3. While in the root directory of the doc project, run the following command to build the documentation:
 
 ```sh
-mkdocs build -f mkdocs-netlify.yml
+mkdocs build 
 ```
 4. Go to the ``site`` directory and open the ``index.html`` file in your web browser to see the documentation.
 5. To automatically rebuild the documentation and reload the browser as you make changes, run the following command:
 
 ```sh
-mkdocs serve -f mkdocs-netlify.yml
+mkdocs serve 
 ```
 
 6. To build the PDF documentation, do the following:
@@ -153,7 +156,6 @@ The repository includes the following directories and files:
 
 - `mkdocs-base.yml` - the base configuration file. It includes general settings and documentation structure.
 - `mkdocs.yml` - configuration file. Contains the settings for building the docs on Percona website
-- `mkdocs-netlify.yml` - configuration file. Contains the settings for building the docs with Material theme.
 - `mkdocs-pdf.yml` - configuration file. Contains the settings for building the PDF docs.
 - `docs`:
   - `*.md` - Source markdown files.

README.md

@@ -6,14 +6,14 @@ Welcome to Percona Distribution for PostgreSQL documentation!
 
 Percona Distribution for PostgreSQL is a collection of tools to assist you in managing your PostgreSQL database system. It includes the upstream version of PostgreSQL and a selection of extensions that enable solving essential practical tasks efficiently.
 
-This repository contains the source files for [Percona Distribution for PostgreSQL documentation](https://www.percona.com/doc/postgresql/13/index.html). The documentation is written in [reStructured text markup language](https://docutils.sourceforge.io/rst.html) and is created using [Sphinx Python Documentation Generator](https://www.sphinx-doc.org/en/master/). 
+This repository contains the source files for [Percona Distribution for PostgreSQL documentation](https://www.percona.com/doc/postgresql/15/index.html). The documentation is written in [Markdown](https://www.markdownguide.org/) markup langiage and is created using [MkDocs Documentation Generator](https://www.mkdocs.org/). 
 
 ## Contributing
 
-We welcome all contributions and are always looking for new members that are as dedicated to serving the community as we are. You can reach out to us using our [forums](https://forums.percona.com/c/postgresql/25) and [Jira issue tracker](https://jira.percona.com/projects/DISTPG/issues/DISTPG-16?filter=allopenissues). 
+We welcome all contributions and are always looking for new members that are as dedicated to serving the community as we are. You can reach out to us using our [forums ](https://forums.percona.com/c/postgresql/25) and [Jira issue tracker ](https://jira.percona.com/projects/DISTPG/issues/DISTPG-16?filter=allopenissues). 
 
-For how to contribute to documentation, read the [Contributing guide](https://github.com/percona/postgresql-docs/blob/13/CONTRIBUTING.md).
+For how to contribute to documentation, read the [Contributing guide ](https://github.com/percona/postgresql-docs/blob/16/CONTRIBUTING.md).
 
 ## License
 
-Percona Distribution for PostgreSQL documentation is licensed under the [PostgreSQL license](https://opensource.org/licenses/postgresql).
+Percona Distribution for PostgreSQL documentation is licensed under the [PostgreSQL license ](https://opensource.org/licenses/postgresql).

docs/apt.md

@@ -1,6 +1,6 @@
 # Install Percona Distribution for PostgreSQL on Debian and Ubuntu
 
-This document describes how to install Percona Server for PostgreSQL from Percona repositories on DEB-based distributions such as Debian and Ubuntu. [Read more about Percona repositories :material-arrow-top-right:](repo-overview.md).
+This document describes how to install Percona Server for PostgreSQL from Percona repositories on DEB-based distributions such as Debian and Ubuntu. [Read more about Percona repositories](repo-overview.md).
 
 ## Preconditions
 
@@ -11,7 +11,7 @@ This document describes how to install Percona Server for PostgreSQL from Percon
 
 Run all the commands in the following sections as root or using the `sudo` command:
 
-### Configure Percona repository
+### Configure Percona repository {.power-number}
 
 1. Install the `percona-release` repository management tool to subscribe to Percona repositories:
 
@@ -53,6 +53,9 @@ Run all the commands in the following sections as root or using the `sudo` comma
 
 === "Install packages individually"
 
+    Run the following commands:
+    {.power-number}
+
      1. Install the PostgreSQL server package:
 
          ```{.bash data-prompt="$"}
@@ -147,34 +150,10 @@ The installation process automatically initializes and starts the default databa
 $ sudo systemctl status postgresql.service
 ```
 
-### Connect to the PostgreSQL server
-
-By default, `postgres` user and `postgres` database are created in PostgreSQL upon its installation and initialization. This allows you to connect to the database as the `postgres` user.
-
-```{.bash data-prompt="$"}
-$ sudo su postgres
-```
-
-Open the PostgreSQL interactive terminal:
-
-```{.bash data-prompt="$"}
-$ psql
-```
-
-!!! hint
-
-    You can connect to `psql` as the `postgres` user in one go:
-
-    ```{.bash data-prompt="$"}
-    $ sudo su - postgres -c psql
-    ```
-
-To exit the `psql` terminal, use the following command:
-
-```{.bash data-prompt="$"}
-$ \q
-```
+Congratulations! Your Percona Distribution for PostgreSQL is up and running.
 
+## Next steps
 
+[Enable extensions :material-arrow-right:](enable-extensions.md){.md-button}
 
-[^1]: Are included in repositories for Debian 12 operating system
+[Connect to PostgreSQL :material-arrow-right:](connect.md){.md-button}

docs/connect.md

@@ -0,0 +1,73 @@
+# Connect to the PostgreSQL server
+
+With PostgreSQL server up and running, let's connect to it.
+
+By default, the `postgres` user and the `postgres` database are created in PostgreSQL upon its installation and initialization. This allows you to connect to the database as the `postgres` user.
+{.power-number}
+
+1. Switch to the `postgres` user.
+
+    ```{.bash data-prompt="$"}
+    $ sudo su postgres
+    ```
+
+2. Open the PostgreSQL interactive terminal `psql`:
+
+    ```{.bash data-prompt="$"}
+    $ psql
+    ```
+
+    <i info>:material-information: Hint:</i> You can connect to `psql` as the `postgres` user in one go: 
+
+    ```{.bash data-prompt="$"}
+    $ sudo su - postgres -c psql
+    ```
+
+
+## Basic `psql` commands
+
+While connected to PostgreSQL, let's practice some basic `psql` commands to interact with the database:
+
+1. List databases:
+
+    ```{.bash data-prompt="$"}
+    $ \l
+    ```
+
+2. Display tables in the current database:
+
+    ```{.bash data-prompt="$"}
+    $ \dt
+    ```
+
+3. Display columns in a table
+
+    ```{.bash data-prompt="$"}
+    $ \d <table_name>
+    ```
+
+4. Switch databases
+
+    ```{.bash data-prompt="$"}
+    $ \c <database_name>
+    ```
+
+5. Display users and roles
+
+    ```{.bash data-prompt="$"}
+    $ \du
+    ```
+
+6. Exit the `psql` terminal:
+
+    ```{.bash data-prompt="$"}
+    $ \q
+    ```
+
+To learn more about using `psql`, see [`psql` :octicons-link-external-16:](https://www.postgresql.org/docs/current/app-psql.html) documentation.
+
+Congratulations! You have connected to PostgreSQL and learned some essential `psql` commands. 
+
+## Next steps
+
+[Manipulate data in PostgreSQL :material-arrow-right:](crud.md){.md-button}

docs/crud.md

@@ -0,0 +1,112 @@
+# Manipulate data in PostgreSQL
+
+On the previous step, you have [connected to PostgreSQL](connect.md) as the superuser `postgres`. Now, let's insert some sample data and operate with it in PostgreSQL.
+
+## Create a database
+
+Let's create the database `test`. Use the CREATE DATABASE command:
+
+```sql
+CREATE DATABASE test;
+```
+
+## Create a table
+
+Let's create a sample table `Customers` in the `test` database using the following command:
+
+```sql
+CREATE TABLE customers (
+    id SERIAL PRIMARY KEY,  -- 'id' is an auto-incrementing integer
+    first_name VARCHAR(50), -- 'first_name' is a string with a maximum length of 50 characters
+    last_name VARCHAR(50),  -- 'last_name' is a string with a maximum length of 50 characters
+    email VARCHAR(100)      -- 'email' is a string with a maximum length of 100 characters
+);
+```
+
+<i info>:material-information: Hint:</i>Having issues with table creation? Check our [Troubleshooting guide](troubleshooting.md)
+
+## Insert the data
+
+Populate the table with the sample data as follows:
+
+```sql
+INSERT INTO customers (first_name, last_name, email)
+VALUES 
+    ('John', 'Doe', '[email protected]'),  -- Insert a new row
+    ('Jane', 'Doe', '[email protected]');
+    ('Alice', 'Smith', '[email protected]');
+```
+
+## Query data
+
+Let's verify the data insertion by querying it:
+
+```sql
+SELECT * FROM customers;
+```
+
+??? example "Expected output"
+
+    ```{.sql .no-copy}
+    id | first_name | last_name |          email
+    ----+------------+-----------+-------------------------
+      1 | John       | Doe       | [email protected]
+      2 | Jane       | Doe       | [email protected]
+      3 | Alice      | Smith     | [email protected]
+    (3 rows)
+    ```
+
+## Update data
+
+Let's update John Doe's record with a new email address.
+
+1. Use the UPDATE command for that:
+
+    ```sql
+    UPDATE customers 
+    SET email = '[email protected]'
+    WHERE first_name = 'John' AND last_name = 'Doe';
+    ```
+
+2. Query the table to verify the updated data:
+
+    ```sql
+    SELECT * FROM customers WHERE first_name = 'John' AND last_name = 'Doe';
+    ```
+
+    ??? example "Expected output"   
+
+        ```{.sql .no-copy}
+         id | first_name | last_name |          email
+        ----+------------+-----------+-------------------------
+          2 | Jane       | Doe       | [email protected]
+          3 | Alice      | Smith     | [email protected]
+          1 | John       | Doe       | [email protected]
+        (3 rows)
+        ```
+
+## Delete data
+
+Use the DELETE command to delete rows. For example, delete the record of Alice Smith:
+
+```sql
+DELETE FROM Customers WHERE first_name = 'Alice' AND last_name = 'Smith';
+```
+
+If you wish to delete the whole table, use the `DROP TABLE` command instead as follows:
+
+```sql
+DROP TABLE customers;
+```
+
+To delete the whole database, use the DROP DATABASE command:
+
+```sql
+DROP DATABASE test;
+```
+
+Congratulations! You have used basic create, read, update and delete (CRUD) operations to manipulate data in Percona Distribution for PostgreSQL. To deepen your knowledge, see the [data manipulation :octicons-link-external-16:](https://www.postgresql.org/docs/{{pgversion}}/dml.html) section in PostgreSQL documentation.
+
+## Next steps
+
+[What's next?](whats-next.md)(.md-button)

docs/docker.md

@@ -1,12 +1,12 @@
 # Run Percona Distribution for PostgreSQL in a Docker container
 
-Docker images of Percona Distribution for PostgreSQL are hosted publicly on [Docker Hub](https://hub.docker.com/r/percona/percona-distribution-postgresql/).
+Docker images of Percona Distribution for PostgreSQL are hosted publicly on [Docker Hub :octicons-link-external-16:](https://hub.docker.com/r/percona/percona-distribution-postgresql/).
 
-For more information about using Docker, see the [Docker Docs](https://docs.docker.com/).
+For more information about using Docker, see the [Docker Docs :octicons-link-external-16:](https://docs.docker.com/).
 
 !!! note ""
 
-    Make sure that you are using the latest version of Docker. The ones provided via `apt` and `yum` may be outdated and cause errors.
+    Make sure that you are using [the latest version of Docker :octicons-link-external-16:](https://docs.docker.com/get-docker/). The ones provided via `apt` and `yum` may be outdated and cause errors.
 
     By default, Docker pulls the image from Docker Hub if it is not available locally.
 
@@ -28,7 +28,7 @@ For more information about using Docker, see the [Docker Docs](https://docs.dock
     | `percona-pg_repack{{pgversion}}`| rebuilds PostgreSQL database objects.| 
     | `percona-wal2json{{pgversion}}` | a PostgreSQL logical decoding JSON output plugin.|
 
-## Start the container
+## Start the container {.power-number}
 
 1. Start a Percona Distribution for PostgreSQL container as follows:
 
@@ -40,7 +40,7 @@ For more information about using Docker, see the [Docker Docs](https://docs.dock
 
     * `container-name` is the name you assign to your container
     * `POSTGRES_PASSWORD` is the superuser password 
-    `tag-multi` is the tag specifying the version you need. For example, `{{dockertag}}-multi`. The `multi` part of the tag serves to identify the architecture (x86_64 or ARM64) and pull the respective image. See the [full list of tags](https://hub.docker.com/r/percona/percona-distribution-postgresql/tags/).     
+    * `tag-multi` is the tag specifying the version you need. For example, `{{dockertag}}-multi`. The `multi` part of the tag serves to identify the architecture (x86_64 or ARM64) and pull the respective image. See the [full list of tags :octicons-link-external-16:](https://hub.docker.com/r/percona/percona-distribution-postgresql/tags/).     
 
 
     !!! tip