Update documentation format for new builder

Author: navarr

Diff for: configuration.md

@@ -1,9 +1,11 @@
 ## Configuration
 
-``` toctree::
-    :maxdepth: 2
-    :caption: Table of Contents
-    :glob:
+```{toctree}
+---
+maxdepth: 2
+caption: Table of Contents
+glob:
+---
 
-    configuration/*
+configuration/*
 ```

Diff for: configuration/blackfire.md

@@ -1,4 +1,4 @@
-## Blackfire Profiling
+# Blackfire Profiling
 
 For information on what Blackfire is, please see the [introduction to Blackfire](https://blackfire.io/docs/introduction) in Blackfire documentation.
 
@@ -15,7 +15,7 @@ BLACKFIRE_SERVER_TOKEN=<server_token>
 
 Note: You can obtain the IDs and Tokens used in the above from within your Blackfire account under Account Settings -> Credentials or from the credentials are of the environment you're pushing profile information into.
 
-### CLI Tool
+## CLI Tool
 
 To use the Blackfire CLI Tool, you can run `warden blackfire [arguments]`.
 

Diff for: configuration/database.md

@@ -1,6 +1,6 @@
-## Database Connections
+# Database Connections
 
-### Common Settings
+## Common Settings
 
 | Name                           | Value/Description                                                |
 | ------------------------------ |----------------------------------------------------------------- |
@@ -14,20 +14,20 @@
 | SSH User                       | `user`                                                           |
 | SSH private key file           | `~/.warden/tunnel/ssh_key`                                       |
 
-### TablePlus
+## TablePlus
 ![TablePlus Connection Info](screenshots/tableplus-connection.png)
 
-### Sequel Pro / Sequel Ace
+## Sequel Pro / Sequel Ace
 ![Sequel Pro Connection Info](screenshots/sequel-pro-connection.png)
 
-### PhpStorm
+## PhpStorm
 ![PHPStorm Connection Config](screenshots/66998481-a0062100-f0d4-11e9-8cc0-a5691fee59c5.png)
 ![PHPStorm Tunnel Config](screenshots/66998483-a09eb780-f0d4-11e9-9643-8fe63dd62aad.png)
 ![PHPStorm Tunnel Config - Windows WSL2](screenshots/123906068-2ed7d180-d97c-11eb-9e52-ec48f6753ee7.png)
 
-### Navicat for MySQL
+## Navicat for MySQL
 ![Navicat Connection Config](screenshots/navicat-connection-config.png)
 ![Navicat Tunnel Config](screenshots/navicat-ssh-tunnel-config.png)
 
-### MySQL Workbench
+## MySQL Workbench
 ![MySQL Workbench](screenshots/mysql-workbench-connection.png)

Diff for: configuration/dns-resolver.md

@@ -1,11 +1,11 @@
-## Automatic DNS Resolution
+# Automatic DNS Resolution
 
 In order to allow automatic DNS resolution using the provided dnsmasq service we will need to make sure DNS request are routed through our local network.
 This requires some configuration.
 
-### Configuration per network
+## Configuration per network
 
-#### Mac
+### Mac
 
 On Mac OS, DNS resolution is configured automatically for `*.test` domains using a feature Mac OS inherits from BSD. When `warden install` is run (or `warden svc up` for the first time) the following contents are placed in the `/etc/resolver/test` file. This has the effect of having zero impact on DNS queries except for those under the `.test` TLD.
 
@@ -21,7 +21,7 @@ If you desire to have more than this route through the `dnsmasq` container, you
 1.0.0.1
 ```
 
-#### systemd-resolved
+### systemd-resolved
 
 This approach works on most modern (systemd based) operating systems.
 
@@ -32,7 +32,7 @@ This approach works on most modern (systemd based) operating systems.
       | sudo tee /etc/systemd/resolved.conf.d/warden.conf > /dev/null
     sudo systemctl restart systemd-resolved
 
-#### Ubuntu resolvconf
+### Ubuntu resolvconf
 
 Use the `resolvconf` service to add a permanent entry in your `/etc/resolv.conf` file.
 
@@ -57,11 +57,11 @@ Restart network-manager
 sudo service network-manager restart
 ```
 
-``` note::
+```{note}
     In the above examples you can replace ``1.1.1.1`` and ``1.0.0.1`` (CloudFlare) with the IP of your own preferred DNS resolution service such as ``8.8.8.8`` and ``8.8.4.4`` (Google) or ``9.9.9.9`` and ``149.112.112.112`` (Quad9)
 ```
 
-#### Windows
+### Windows
 
 Add the local dnsmasq resolver as the first DNS server:
 

Diff for: configuration/livereload.md

@@ -1,8 +1,8 @@
-## LiveReload Setup
+# LiveReload Setup
 
 LiveReload routing is currently supported only on the `magento2` environment type. Other environment types may utilize LiveReload via per-project compose configurations to setup the routing for LiveReload JS and WebSocket endpoints.
 
-### Configuration for Magento 2
+## Configuration for Magento 2
 
 Magento 2 bundles an example grunt based server-side compilation workflow which includes LiveReload and it works within the Warden shell environment. In order to use this:
 
@@ -29,7 +29,7 @@ Magento 2 bundles an example grunt based server-side compilation workflow which
    ];
    ```
 
-   ``` note::
+   ```{note}
        This can be accomplished via alternative means, the important part is the browser requesting ``/livereload.js?port=443`` when running the site on your local development environment.
    ```
 
@@ -51,7 +51,7 @@ Magento 2 bundles an example grunt based server-side compilation workflow which
    grunt watch
    ```
 
-   ``` note::
+   ```{note}
        Grunt should be used within the php-fpm container entered via ``warden shell``
    ```
 

Diff for: configuration/magento2-testing.md

@@ -35,7 +35,7 @@ That's it! Now you are ready to run Unit Tests.
 
 ### Debugging
 
-If you have [configured Xdebug](xdebug.md), run Unit tests inside **Debug** console (`warden debug` instead of `warden shell`). The code execution will stop at the breakpoints.
+If you have {doc}`configured Xdebug <xdebug>`, run Unit tests inside **Debug** console (`warden debug` instead of `warden shell`). The code execution will stop at the breakpoints.
 
 ## Running Javascript Unit Tests
 
@@ -133,7 +133,7 @@ There's one thing you should be aware of: **always provide full path to `phpunit
 
 ### Debugging
 
-If you have [configured Xdebug](xdebug.md), run Integration tests inside **Debug** console (`warden debug` instead of `warden shell`). The code execution will stop at the breakpoints.
+If you have {doc}`configured Xdebug <xdebug>`, run Integration tests inside **Debug** console (`warden debug` instead of `warden shell`). The code execution will stop at the breakpoints.
 
 
 ### Troubleshooting
@@ -203,7 +203,7 @@ There's one thing you should be aware of: **always provide full path to `phpunit
 
 ### Debugging
 
-If you have [configured Xdebug](xdebug.md), run Integration tests inside **Debug** console (`warden debug` instead of `warden shell`). The code execution will stop at the breakpoints.
+If you have {doc}`configured Xdebug <xdebug>`, run Integration tests inside **Debug** console (`warden debug` instead of `warden shell`). The code execution will stop at the breakpoints.
 
 ## Running API Functional Tests
 
@@ -282,12 +282,13 @@ When debugging APIs you may need to use Xdebug - configure your `phpunit_{type}.
 
    - `TESTS_XDEBUG_ENABLED` to `true`
    - `TESTS_XDEBUG_SESSION` to `phpstorm`
-   
+
+(magento2-testing-running-mftf-tests)=
 ## Running MFTF Tests
 
 All the MFTF-related operations are operated by `vendor/bin/mftf`, necessary files are located in `dev/tests/acceptance/`.
 
-To run Acceptance tests you need to [configure the MFTF environment](mftf.md). Once you've done that, follow these steps to run the tests.
+To run Acceptance tests you need to {doc}`configure the MFTF environment <mftf>`. Once you've done that, follow these steps to run the tests.
 
 1. Make sure that you enabled following in your `.env` file:
     - `WARDEN_SELENIUM` - Responsible for running virtual browser for your tests
@@ -320,7 +321,7 @@ To run Acceptance tests you need to [configure the MFTF environment](mftf.md). O
 
 ### Debugging
 
-For more information about Debugging MFTF - please follow the [Magento Functional Testing Framework](mftf.md) section.
+For more information about Debugging MFTF - please follow the {doc}`Magento Functional Testing Framework <mftf>` section.
 The process of debugging is based on VNC connection to the Chrome instance.
 
 You can connect to Chrome session with `warden vnc` command.

Diff for: configuration/mftf.md

@@ -1,4 +1,4 @@
-## Magento Functional Testing Framework
+# Magento Functional Testing Framework
 
 For information what **Magento Functional Testing Framework** is - please follow to [MFTF DevDocs](https://devdocs.magento.com/mftf/docs/introduction.html).
 
@@ -15,11 +15,11 @@ SELENIUM_HOST=selenium
 BROWSER=chrome
 ```
 
-### Running Tests
+## Running Tests
 
-We provide complex instruction on [How to run MFTF Tests](magento2-testing.html#running-mftf-tests) in Warden environment.
+We provide complex instruction on {ref}`How to run MFTF Tests <magento2-testing-running-mftf-tests>` in Warden environment.
 
-### Debugging MFTF Tests
+## Debugging MFTF Tests
 
 By default Warden uses headless Chrome browser. If you want to preview the tests - you need to extend `.env` file and update environment containers (`warden env up`)
 
@@ -31,15 +31,15 @@ WARDEN_SELENIUM_DEBUG=1
 
 To preview the process of testing, you need any **VLC** client that provides **SSH Tunnel** support (eg. [Remmina](https://remmina.org/how-to-install-remmina/)). To preview the process of testing, you need to use `tunnel.warden.test:2222` (login: `user`):
 
-### Remote Desktop Viewer
+## Remote Desktop Viewer
 
   ![Remote Desktop Viewer](screenshots/selenium-remote-desktop-viewer.png)
 
-### Remmina
+## Remmina
 
   ![Remmina Configuration](screenshots/remmina-ssh-tunnel.png)
 
-### Mac OS X
+## Mac OS X
 
 To preview the process in Mac OS X, you must first create an SSH tunnel to the docker instance hosting the VNC server.  That would look something like:
 

Diff for: configuration/multipledomains.md

@@ -1,4 +1,4 @@
-## Multiple Domains
+# Multiple Domains
 
 If you need multiple domains configured for your project, Warden will now automatically route all sub-domains of the configured `TRAEFIK_DOMAIN` (as given when running `env-init`) to the Varnish/Nginx containers provided there is not a more specific rule such as for example `rabbitmq.exampleproject.com` which routes to the `rabbitmq` service for the project.
 
@@ -38,7 +38,7 @@ Multiple top-level domains may also be setup by following the instructions below
 
 4. Run `warden env up` to update the containers, after which each of the URLs should work as expected.
 
-    ``` note::
+    ```{note}
         If these alternate domains must be resolvable from within the FPM containers, you must also leverage ``extra_hosts`` to add each specific sub-domain to the ``/etc/hosts`` file of the container as dnsmasq is used only on the host machine, not inside the containers. This should look something like the following excerpt.
 
     ```
@@ -65,7 +65,7 @@ Multiple top-level domains may also be setup by following the instructions below
          - sub2.alternate2.test:${TRAEFIK_ADDRESS:-0.0.0.0}
     ```
 
-### Magento 2 Run Params
+## Magento 2 Run Params
 
 When multiple domains are being used to load different stores or websites on Magento 2, the following configuration should be defined in order to set run codes and types as needed.
 
@@ -100,7 +100,7 @@ When multiple domains are being used to load different stores or websites on Mag
     }
     ```
 
-    ``` note::
+    ```{note}
         The above example will not alter production site behavior given the default is to return should the ``HTTP_HOST`` value not match one of the defined ``case`` statements. This is desired as some hosting environments define run codes and types in an Nginx mapping. One may add production host names to the switch block should it be desired to use the same site switching mechanism across all environments.
     ```
 
@@ -116,7 +116,7 @@ When multiple domains are being used to load different stores or websites on Mag
     }
     ```
 
-    ``` note::
+    ```{note}
         This is similar to using `magento-vars.php` on Magento Commerce Cloud, but using composer to load the file rather than relying on Commerce Cloud magic: https://devdocs.magento.com/guides/v2.3/cloud/project/project-multi-sites.html
     ```
 

Diff for: configuration/xdebug.md

@@ -1,4 +1,4 @@
-## Xdebug Support
+# Xdebug Support
 
 There are two docker containers running FPM, `php-fpm`, `php-debug`. The `php-debug` container has the **Xdebug** extension pre-installed. Nginx will automatically route requests to the `php-debug` container when the `XDEBUG_SESSION` cookie has been set to `PHPSTORM` via the Xdebug Helper browser extension.
 
@@ -12,7 +12,7 @@ In similar fashion to the `warden shell` command there is also a debug command t
 warden debug
 ```
 
-### VSCode
+## VSCode
 
 To configure a project in VSCode for debugging, add the following to `.vscode/launch.json` in the project directory:
 
@@ -33,15 +33,15 @@ To configure a project in VSCode for debugging, add the following to `.vscode/la
 }
 ```
 
-``` note::
+```{note}
     If your project has (for example) ``WARDEN_WEB_ROOT=/webroot`` in it's ``.env`` file, to mount ``webroot/`` to ``/var/www/html`` rather than the top-level project directory, you may need to set the ``pathMapping`` above to ``${workspaceRoot}/webroot`` for the mapping to function correctly.
 ```
 
 Once this configuration is in place, make sure you have the [PHP Debug extension by Felix Becker](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug) installed. This is required for Xdebug support to function in VSCode. Additional information on launch settings specific to Xdebug use in VSCode [may be found here](https://github.com/felixfbecker/vscode-php-debug#vs-code-configuration).
 
 To learn more about debugging in VSCode, [please go here](https://code.visualstudio.com/docs/editor/debugging).
 
-### PhpStorm
+## PhpStorm
 
 When it receives the first request, PHP Storm should prompt you if the "Server" configuration is missing. The below image demonstrates how this is setup; the important settings are these:
 

Diff for: environments.md

@@ -1,12 +1,14 @@
 ## Environments
 
-``` toctree::
-    :maxdepth: 2
-    :caption: Table of Contents
-    :glob:
+```{toctree}
+---
+maxdepth: 2
+caption: Table of Contents
+glob:
+---
 
-    environments/types
-    environments/magento2
-    environments/shopware
-    environments/*
+environments/types
+environments/magento2
+environments/shopware
+environments/*
 ```

Diff for: environments/customizing.md

@@ -1,4 +1,4 @@
-## Customizing An Environment
+# Customizing An Environment
 
 Further information on customizing or extending an environment is forthcoming. For now, this section is limited to very simple and somewhat common customizations.
 
@@ -21,13 +21,13 @@ Start of some environments could be skipped by using variables in `.env` file:
   * `WARDEN_DB=0`
   * `WARDEN_REDIS=0`
 
-### Docker Specific Customizations
+## Docker Specific Customizations
 To override default docker settings, add a custom configuration file in your project root
 folder: `/.warden/warden-env.yml`
 This file will be merged with the default environment configuration.
 One example for a use case is [the setup of multiple domains](https://docs.warden.dev/configuration/multipledomains.html?highlight=warden%20env%20yml#multiple-domains).
 
-### PHP Specific Customizations
+## PHP Specific Customizations
 To override default php settings, follow the docker customization above and include your custom `php.ini` file.
 In this case the `warden-env.yml` should look like this:
 
@@ -58,7 +58,7 @@ post_max_size = 25M
 session.auto_start = Off
 upload_max_filesize = 25M
 ```
-### Nginx Specific Customizations
+## Nginx Specific Customizations
 To override the default nginx configuration of your project, add a new file 
 `.warden/warden-env.yml` to your project root with the following content:
 ```
@@ -70,12 +70,12 @@ services:
 ```
 There you can specify a custom Nginx configuration which will be included following the `.conf` files within the `/etc/nginx/available.d` directory: `include /etc/nginx/default.d/*.conf`
 
-### Magento 1 Specific Customizations
+## Magento 1 Specific Customizations
 
 If you use a `modman` structure, initialize the environment in your project path. 
 The `.modman` folder and the corresponding `.basedir` file will be recognized and set up automatically. 
 
-### Magento 2 Specific Customizations
+## Magento 2 Specific Customizations
 
 The following variables can be added to the project's `.env` file to enable additional database containers for use with the Magento 2 (Commerce Only) [split-database solution](https://devdocs.magento.com/guides/v2.3/config-guide/multi-master/multi-master.html).
 

Diff for: environments/magento2.md

@@ -1,4 +1,4 @@
-## Installing Magento 2
+# Installing Magento 2
 
 The below example demonstrates the from-scratch setup of the Magento 2 application for local development. A similar process can easily be used to configure an environment of any other type. This assumes that Warden has been previously started via `warden svc up` as part of the installation procedure.
 

Diff for: environments/shopware.md

@@ -1,4 +1,4 @@
-## Installing Shopware 6
+# Installing Shopware 6
 
 The below example demonstrates the from-scratch setup of the Shopware 6 application for local development. A similar process can easily be used to configure an environment of any other type. This assumes that Warden has been previously started via `warden svc up` as part of the installation procedure.