find and replace fixes, will introduce errors

docs/customizing/index.md

@@ -2,7 +2,7 @@
 
 It is possible to customize your **Alliance Auth** instance.
 
-```eval_rst
+```{eval-rst}
 .. warning::
     Keep in mind that you may need to update some of your customizations manually after new Auth releases (e.g. when replacing templates).
 ```
@@ -82,7 +82,7 @@ First you need to create the folder for the template on your server. For AA to p
 
 If you have a default installation you can create the folder like this:
 
-```sh
+```shell
 mkdir -p /home/allianceserver/myauth/myauth/templates/allianceauth
 ```
 
@@ -90,7 +90,7 @@ mkdir -p /home/allianceserver/myauth/myauth/templates/allianceauth
 
 Next you need to download a copy of the original template file we want to change. For that let's move into the above folder and then download the file into the current folder with:
 
-```sh
+```shell
 cd /home/allianceserver/myauth/myauth/templates/allianceauth
 wget <https://gitlab.com/allianceauth/allianceauth/-/raw/master/allianceauth/templates/allianceauth/side-menu.html>
 ```
@@ -99,11 +99,11 @@ wget <https://gitlab.com/allianceauth/allianceauth/-/raw/master/allianceauth/tem
 
 Now you can modify the template to add your custom link. To create the google link we can add this snippet *between* the `{% menu_items %}` and the `</ul>` tag:
 
-```sh
+```shell
 nano /home/allianceserver/myauth/myauth/templates/allianceauth/side-menu.html
 ```
 
-```jinja
+```django
     <li>
         <a href="https://www.google.com/" target="_blank">
             <i class="fab fa-google fa-fw"></i>Google
@@ -111,7 +111,7 @@ nano /home/allianceserver/myauth/myauth/templates/allianceauth/side-menu.html
     </li>
 ```
 
-```eval_rst
+```{eval-rst}
 .. hint::
     You can find other icons with a matching style on the `Font Awesome site <https://fontawesome.com/v5/search?m=free>`_ . AA currently uses Font Awesome version 5. You also want to keep the ``fa-fw`` tag to ensure all icons have the same width.
 ```

docs/development/aa_core/documentation.md

@@ -4,13 +4,13 @@ The documentation for Alliance Auth uses [Sphinx](http://www.sphinx-doc.org/) to
 to specific branches is made (master, primarily), the repository is automatically pulled, docs built and deployed on
 [readthedocs.org](https://readthedocs.org/).
 
-
 Documentation was migrated from the GitHub wiki pages and into the repository to allow documentation changes to be
 included with pull requests. This means that documentation can be guaranteed to be updated when a pull request is
 accepted rather than hoping documentation is updated afterwards or relying on maintainers to do the work. It also
 allows for documentation to be maintained at different versions more easily.
 
 ## Building Documentation
+
 If you're developing new documentation, its likely you'll want or need to test build it before committing to your
 branch. To achieve this you can use Sphinx to build the documentation locally as it appears on Read the Docs.
 
@@ -24,15 +24,16 @@ build in the `/docs/_build/` directory.
 Occasionally you may need to fully rebuild the documents by running `make clean` first, usually when you add or
 rearrange toctrees.
 
-
 ## Documentation Format
 
-CommonMark Markdown is the current preferred format, via [recommonmark](https://github.com/rtfd/recommonmark).
+CommonMark-plus Markdown is the current preferred format, via [MyST-Parser](https://github.com/executablebooks/MyST-Parser).
-reStructuredText is supported if required, or you can execute snippets of reST inside Markdown by using a code block:
+reStructuredText is supported if required, or you can execute snippets of MyST inside Markdown by using a code block:
 
-    ```eval_rst
+````md
+```{eval-rst}
 reStructuredText here
 ```
+````
 
 Markdown is used elsewhere on Github so it provides the most portability of documentation from Issues and Pull Requests
 as well as providing an easier initial migration path from the Github wiki.

docs/development/aa_core/index.md

@@ -2,8 +2,7 @@
 
 This section contains important information on how to develop Alliance Auth itself.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 documentation

docs/development/custom/index.md

@@ -2,8 +2,7 @@
 
 This section describes how to extend **Alliance Auth** with custom apps and services.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 integrating-services

docs/development/custom/integrating-services.md

@@ -46,7 +46,7 @@ In order to integrate with Alliance Auth service modules must provide a `service
 
 This would register the ExampleService class which would need to be a subclass of `services.hooks.ServiceHook`.
 
-```eval_rst
+```{eval-rst}
 .. important::
     The hook **MUST** be registered in ``yourservice.auth_hooks`` along with any other hooks you are registering for Alliance Auth.
 ```

docs/development/custom/menu-hooks.md

@@ -40,7 +40,7 @@ A list of views or namespaces the link should be highlighted on. See [django-nav
 
 This is a great feature to signal the user, that he has some open issues to take care of within an app. For example Auth uses this feature to show the specific number of open group request to the current user.
 
-```eval_rst
+```{eval-rst}
 .. hint::
     Here is how to stay consistent with the Auth design philosophy for using this feature:
     1. Use it to display open items that the current user can close by himself only. Do not use it for items, that the user has no control over.

docs/development/custom/url-hooks.md

@@ -18,8 +18,7 @@ In addition is it possible to make views public. Normally, all views are automat
 
 An app can opt-out of this feature by adding a list of views to be excluded when registering the URLs. See the `excluded_views` parameter for details.
 
-```eval_rst
+:::{note}
-.. note::
     Note that for a public view to work, administrators need to also explicitly allow apps to have public views in their AA installation, by adding the apps label to ``APPS_WITH_PUBLIC_VIEWS`` setting.
 ```
 
@@ -59,7 +58,7 @@ When this app is included in the project's `settings.INSTALLED_APPS` users would
 
 ## API
 
-```eval_rst
+```{eval-rst}
 .. autoclass:: allianceauth.services.hooks.UrlHook
     :members:
 ```

docs/development/dev_setup/aa-dev-setup-wsl-vsc-v2.md

@@ -6,7 +6,7 @@ The main benefit of this setup is that it runs all services and code in the nati
 
 In addition all tools described in this guide are open source or free software.
 
-```eval_rst
+```{eval-rst}
 .. hint::
     This guide is meant for development purposes only and not for installing AA in a production environment. For production installation please see chapter **Installation**.
 ```
@@ -25,8 +25,7 @@ The development environment consists of the following components:
 
 We will use the build-in Django development web server, so we don't need to setup a WSGI server or a web server.
 
-```eval_rst
+:::{note}
-.. note::
     This setup works with both WSL 1 and WSL 2. However, due to the significantly better performance we recommend WSL 2.
 ```
 
@@ -58,13 +57,13 @@ The only requirement is a PC with Windows 10 and Internet connection in order to
 
 Open a WSL bash and update all software packets:
 
-```bash
+```shell
 sudo apt update && sudo apt upgrade -y
 ```
 
 ### Install Tools
 
-```bash
+```shell
 sudo apt-get install build-essential
 sudo apt-get install gettext
 ```
@@ -73,13 +72,12 @@ sudo apt-get install gettext
 
 Next we need to install Python and related development tools.
 
-```eval_rst
+```{eval-rst}
 .. hint::
     To check your system's Python 3 version you can enter: ``python3 --version``
 ```
 
-```eval_rst
+:::{note}
-.. note::
     Should your Ubuntu come with a newer version of Python we recommend to still setup your dev environment with the oldest Python 3 version currently supported by AA (e.g Python 3.8 at this time of writing) to ensure your apps are compatible with all current AA installations
     You an check out this `page <https://askubuntu.com/questions/682869/how-do-i-install-a-different-python-version-using-apt-get/1195153>`_ on how to install additional Python versions on Ubuntu.
 
@@ -90,19 +88,19 @@ Next we need to install Python and related development tools.
 
 Use the following command to install Python 3 with all required libraries with the default version:
 
-```bash
+```shell
 sudo apt-get install python3 python3-dev python3-venv python3-setuptools python3-pip python-pip
 ```
 
 ### Install redis and other tools
 
-```bash
+```shell
 sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev pkg-config
 ```
 
 Start redis
 
-```bash
+```shell
 sudo redis-server --daemonize yes
 ```
 
@@ -110,30 +108,29 @@ sudo redis-server --daemonize yes
 
 Install MySQL and required libraries with the following command:
 
-```bash
+```shell
 sudo apt-get install mysql-server mysql-client libmysqlclient-dev
 ```
 
-```eval_rst
+:::{note}
-.. note::
     We chose to use MySQL instead of MariaDB, because the standard version of MariaDB that comes with this Ubuntu distribution will not work with AA.
 ```
 
 We need to apply a permission fix to mysql or you will get a warning with every startup:
 
-```bash
+```shell
 sudo usermod -d /var/lib/mysql/ mysql
 ```
 
 Start the mysql server
 
-```bash
+```shell
 sudo service mysql start
 ```
 
 Create database and user for AA
 
-```bash
+```shell
 sudo mysql -u root
 ```
 
@@ -147,12 +144,11 @@ exit;
 
 Add timezone info to mysql:
 
-```bash
+```shell
 sudo mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root mysql
 ```
 
-```eval_rst
+:::{note}
-.. note::
     If your WSL does not have an init.d service, it will not automatically start your services such as MySQL and Redis when you boot your Windows machine and you have to manually start them. For convenience we recommend putting these commands in a bash script. Here is an example:
 
     ::
@@ -183,7 +179,7 @@ Following this approach you can also setup additional AA projects, e.g. aa-dev-2
 
 Create the root folder `aa-dev`.
 
-```eval_rst
+```{eval-rst}
 .. hint::
     The folders `venv` and `myauth` will be created automatically in later steps. Please do not create them manually as this would lead to errors.
 ```
@@ -192,19 +188,19 @@ Create the root folder `aa-dev`.
 
 Create the virtual environment. Run this in your aa-dev folder:
 
-```bash
+```shell
 python3 -m venv venv
 ```
 
 And activate your venv:
 
-```bash
+```shell
 source venv/bin/activate
 ```
 
 ### Install and update basic Python packages
 
-```bash
+```shell
 pip install -U pip setuptools wheel
 ```
 
@@ -212,19 +208,19 @@ pip install -U pip setuptools wheel
 
 ### Install and create AA instance
 
-```bash
+```shell
 pip install allianceauth
 ```
 
 Now we are ready to setup our AA instance. Make sure to run this command in your aa-dev folder:
 
-```bash
+```shell
 allianceauth start myauth
 ```
 
 Next we will setup our VSC project for aa-dev by starting it directly from the WSL bash:
 
-```bash
+```shell
 code .
 ```
 
@@ -244,7 +240,7 @@ For the Eve Online related setup you need to create a SSO app on the developer s
 
 Open your local Django settings with VSC. The file is under `myauth/myauth/settings/local.py`
 
-```eval_rst
+```{eval-rst}
 .. hint::
     There are two Django settings files: ``base.py`` and ``local.py``. The base settings file is controlled by the AA project and may change at any time. It is therefore recommended to only change the local settings file.
 ```
@@ -293,14 +289,14 @@ REGISTRATION_VERIFY_EMAIL = False
 
 Before we can start AA we need to run migrations:
 
-```bash
+```shell
 cd myauth
 python manage.py migrate
 ```
 
 We also need to create a superuser for our AA installation:
 
-```bash
+```shell
 python manage.py createsuperuser
 ```
 
@@ -310,19 +306,18 @@ python manage.py createsuperuser
 
 We are now ready to run out AA instance with the following command:
 
-```bash
+```shell
 python manage.py runserver
 ```
 
 Once running you can access your auth site on the browser under `http://localhost:8000`. Or the admin site under `http://localhost:8000/admin`
 
-```eval_rst
+```{eval-rst}
 .. hint::
     You can start your AA server directly from a terminal window in VSC or with a VSC debug config (see chapter about debugging for details).
 ```
 
-```eval_rst
+:::{note}
-.. note::
     **Debug vs. Non-Debug mode**
     Usually it is best to run your dev AA instance in debug mode, so you get all the detailed error messages that helps a lot for finding errors. But there might be cases where you want to test features that do not exist in debug mode (e.g. error pages) or just want to see how your app behaves in non-debug / production mode.
 
@@ -335,7 +330,7 @@ In addition you can start a celery worker instance for myauth. For development p
 
 This can be done from the command line with the following command in the myauth folder (where manage.py is located):
 
-```bash
+```shell
 celery -A myauth worker -l info -P solo
 ```
 
@@ -499,7 +494,7 @@ Open a WSL bash and navigate to the aa-dev folder. Make sure you have activate y
 
 Run these commands:
 
-```bash
+```shell
 git clone https://gitlab.com/ErikKalkoken/allianceauth-example-plugin.git
 pip install -e allianceauth-example-plugin
 ```
@@ -508,7 +503,7 @@ Add `'example'` to INSTALLED_APPS in your `local.py` settings.
 
 Run migrations and restart your AA server, e.g.:
 
-```bash
+```shell
 cd myauth
 python manage.py migrate
 ```

docs/development/dev_setup/index.md

@@ -2,8 +2,7 @@
 
 Here you find guides on how to setup your development environment for AA.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 aa-dev-setup-wsl-vsc-v2

docs/development/index.md

@@ -2,8 +2,7 @@
 
 **Alliance Auth** is designed to be extended easily. Learn how to develop your own apps and services for AA or to develop for AA core in the development chapter.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 custom/index

docs/development/tech_docu/api/index.md

@@ -2,8 +2,7 @@
 
 To reduce redundancy and help speed up development we encourage developers to utilize the following packages when developing apps for Alliance Auth.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 discord_client

docs/development/tech_docu/celery.md

@@ -14,8 +14,7 @@ Alliance Auth is an online web application and as such the user expects fast and
 
 As a rule of thumb we therefore recommend to use celery tasks for every process that can take longer than 1 sec to complete (also think about how long your process might take with large amounts of data).
 
-```eval_rst
+:::{note}
-.. note::
     Another solution for dealing with long response time in particular when loading pages is to load parts of a page asynchronously, for example with AJAX.
 ```
 
@@ -106,7 +105,7 @@ In this example we fist add 10 example tasks that need to run one after the othe
 
 The list of task signatures is then converted to a chain and started asynchronously.
 
-```eval_rst
+```{eval-rst}
 .. hint::
     In our example we use ``si()``, which is a shortcut for "immutable signatures" and prevents us from having to deal with result sharing between tasks.
 
@@ -137,7 +136,7 @@ CELERYBEAT_SCHEDULE['structures_update_all_structures'] = {
 
 In Alliance Auth we have defined task priorities from 0 - 9 as follows:
 
-```eval_rst
+```{eval-rst}
     ====== ========= ===========
     Number Priority  Description
     ====== ========= ===========
@@ -150,14 +149,14 @@ In Alliance Auth we have defined task priorities from 0 - 9 as follows:
     ====== ========= ===========
 ```
 
-```eval_rst
+```{eval-rst}
 .. warning::
     Please make sure to use task priorities with care and especially do not use higher priorities without a good reason. All apps including Alliance Auth share the same task queues, so using higher task priorities excessively can potentially prevent more important tasks (of other apps) from completing on time.
 
     You also want to make sure to run use lower priorities if you have a large amount of tasks or long running tasks, which are not super urgent. (e.g. the regular update of all Eve characters from ESI runs with priority 7)
 ```
 
-```eval_rst
+```{eval-rst}
 .. hint::
     If no priority is specified all tasks will be started with the default priority, which is 5.
 ```
@@ -170,7 +169,7 @@ Example for starting a task with priority 3:
 example.apply_async(priority=3)
 ```
 
-```eval_rst
+```{eval-rst}
 .. hint::
     For defining a priority to tasks you can not use the convenient shortcut ``delay()``, but instead need to start a task with ``apply_async()``, which also requires you to pass parameters to your task function differently. Please check out the `official docs <https://docs.celeryproject.org/en/stable/reference/celery.app.task.html#celery.app.task.Task.apply_async>`_ for details.
 ```

docs/development/tech_docu/index.md

@@ -2,8 +2,7 @@
 
 In this section you find topics useful for app developers.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 api/index

docs/features/apps/autogroups.md

@@ -1,7 +1,6 @@
 # Auto Groups
 
-```eval_rst
+:::{note}
-.. note::
     New in 2.0
 ```
 
@@ -19,7 +18,7 @@ When you create an autogroup config you will be given the following options:
 
 ![Create Autogroup page](/_static/images/features/apps/autogroups/group-creation.png)
 
-```eval_rst
+```{eval-rst}
 .. warning::
     After creating a group you wont be able to change the Corp and Alliance group prefixes, name source and the replace spaces settings. Make sure you configure these the way you want before creating the config. If you need to change these you will have to create a new autogroup config.
 ```
@@ -38,7 +37,7 @@ When you create an autogroup config you will be given the following options:
 
 Auto Groups are configured via models in the Admin Interface, a user will require the `Staff` Flag in addition to the following permissions.
 
-```eval_rst
+```{eval-rst}
 +-------------------------------------------+------------------+----------------+
 | Permission                                | Admin Site       | Auth Site      |
 +===========================================+==================+================+

docs/features/apps/corpstats.md

@@ -90,7 +90,7 @@ Characters from all Corp Stats to which the user has view access will be display
 
 To use this feature, users will require some of the following:
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+----------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                          |
 +=======================================+==================+====================================================+

docs/features/apps/fleetactivitytracking.md

@@ -16,7 +16,7 @@ To administer this feature, users will require some of the following.
 
 Users do not require any permissions to interact with FAT Links created.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/features/apps/hrapplications.md

@@ -44,7 +44,7 @@ To administer this feature, users will require some of the following.
 
 Users do not require any permission to apply to a corporation and fill out the form.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+----------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                          |
 +=======================================+==================+====================================================+

docs/features/apps/index.md

@@ -2,8 +2,7 @@
 
 **Alliance Auth** comes with a set of apps (also called plugin-apps) which provide basic functions useful to many organizations in Eve Online like a fleet schedule and a timerboard. This section describes which apps are available and how to install and use them. Please note that any app need to be installed before it can be used.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 autogroups

docs/features/apps/optimer.md

@@ -12,7 +12,7 @@ Add `'allianceauth.optimer',` to your `INSTALLED_APPS` list in your auth project
 
 To use and administer this feature, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/features/apps/permissions_tool.md

@@ -42,7 +42,7 @@ Please note that users may appear multiple times if this permission is granted v
 
 To use this feature, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/features/apps/srp.md

@@ -12,7 +12,7 @@ Add `'allianceauth.srp',` to your `INSTALLED_APPS` list in your auth project's s
 
 To use and administer this feature, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +----------------------+------------------+------------------------------------------------------------+
 | Permission           | Admin Site       | Auth Site                                                  |
 +======================+==================+============================================================+

docs/features/apps/timerboard.md

@@ -12,7 +12,7 @@ Add `'allianceauth.timerboard',` to your `INSTALLED_APPS` list in your auth proj
 
 To use and administer this feature, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/features/core/admin_site.md

@@ -10,7 +10,7 @@ You can open the admin site by clicking on "Admin" in the drop down menu for a u
 
 For small to medium size alliances it is often sufficient to have no more then two superuser admins (admins that also are superusers). Having two admins usually makes sense, so you can have one primary and one backup.
 
-```eval_rst
+```{eval-rst}
 .. warning::
     Superusers have read & write access to everything on your AA installation. Superusers also automatically have all permissions and therefore access to all features of your apps. Therefore we recommend to be very careful to whom you give superuser privileges.
 ```
@@ -26,8 +26,7 @@ To create a staff admin you need to do two things:
 1. Enable the `is_staff` property for a user
 1. Give the user permissions for admin tasks
 
-```eval_rst
+:::{note}
-.. note::
     Note that staff admins have the following limitations:
 
     - Can not promote users to staff
@@ -42,7 +41,7 @@ To create a staff admin you need to do two things:
 Access to the admin site is restricted. Users needs to have the `is_staff` property to be able to open the site at all. The superuser that is created during the installation
 process will automatically have access to the admin site.
 
-```eval_rst
+```{eval-rst}
 .. hint::
     Without any permissions a "staff user" can open the admin site, but can neither view nor edit anything except for viewing the list of permissions.
 ```

docs/features/core/analytics.md

@@ -64,7 +64,7 @@ This data is stored in a Team Google Analytics Dashboard. The Maintainers all ha
 
 ### Analytics Event
 
-```eval_rst
+```{eval-rst}
 .. automodule:: allianceauth.analytics.tasks
     :members: analytics_event
     :undoc-members:

docs/features/core/dashboard.md

@@ -13,7 +13,7 @@ For admin users the dashboard shows additional technical information about the
 Here is a list of available settings for the dashboard. They can be configured by adding them to your AA settings file (``local.py``).
 Note that all settings are optional and the app will use the documented default settings if they are not used.
 
-```eval_rst
+```{eval-rst}
 +-----------------------------------------------------+-------------------------------------------------------------------------+-----------+
 | Name                                                | Description                                                             | Default   |
 +=====================================================+=========================================================================+===========+

docs/features/core/groups.md

@@ -42,7 +42,7 @@ Most people won't have a use for public groups, though it can be useful if you w
 
 When a group is restricted only superuser admins can directly add or remove them to/from users. The purpose of this property is prevent staff admins from assigning themselves to groups that are security sensitive. The "restricted" property can be combined with all the other properties.
 
-```eval_rst
+```{eval-rst}
 .. _ref-reserved-group-names:
 ```
 
@@ -50,8 +50,7 @@ When a group is restricted only superuser admins can directly add or remove them
 
 When using Alliance Auth to manage external services like Discord, Auth will automatically duplicate groups on those services. E.g. on Discord Auth will create roles of the same name as groups. However, there may be cases where you want to manage groups on external services by yourself or by another bot. For those cases you can define a list of reserved group names. Auth will ensure that you can not create groups with a reserved name. You will find this list on the admin site under groupmanagement.
 
-```eval_rst
+:::{note}
-.. note::
     While this feature can help to avoid naming conflicts with groups on external services, the respective service component in Alliance Auth also needs to be build in such a way that it knows how to prevent these conflicts. Currently only the Discord and Teamspeak3 services have this ability.
 ```
 
@@ -101,8 +100,7 @@ By default, in AA both requests and leaves for non-open groups must be approved
 GROUPMANAGEMENT_AUTO_LEAVE = True
 ```
 
-```eval_rst
+:::{note}
-.. note::
     Before you set `GROUPMANAGEMENT_AUTO_LEAVE = True`, make sure there are no pending leave requests, as this option will hide the "Leave Requests" tab.
 ```
 
@@ -111,7 +109,7 @@ GROUPMANAGEMENT_AUTO_LEAVE = True
 Here is a list of available settings for Group Management. They can be configured by adding them to your AA settings file (``local.py``).
 Note that all settings are optional and the app will use the documented default settings if they are not used.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------------+---------------------------------------------------------------------------+------------+
 | Name                                        | Description                                                               | Default    |
 +=============================================+===========================================================================+============+
@@ -127,14 +125,13 @@ In order to join a group other than a public group, the permission `groupmanagem
 
 When a user loses this permission, they will be removed from all groups _except_ Public groups.
 
-```eval_rst
+:::{note}
-.. note::
     By default, the ``groupmanagement.request_groups`` permission is applied to the ``Member`` group. In most instances this, and perhaps adding it to the ``Blue`` group, should be all that is ever needed. It is unsupported and NOT advisable to apply this permission to a public group. See #697 for more information.
 ```
 
 Group Management should be mostly done using group leaders, a series of permissions are included below for thoroughness:
 
-```eval_rst
+```{eval-rst}
 +--------------------------------+-------------------+------------------------------------------------------------------------------------+
 | Permission                     | Admin Site        | Auth Site                                                                          |
 +================================+===================+====================================================================================+

docs/features/core/index.md

@@ -2,8 +2,7 @@
 
 Managing access to applications and services is one of the core functions of **Alliance Auth**. The related key concepts and functionalities are describes in this section.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 dashboard

docs/features/index.md

@@ -2,8 +2,7 @@
 
 Learn about the features of **Alliance Auth** and how to install and use them.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 overview

docs/features/services/discord.md

@@ -33,8 +33,7 @@ CELERYBEAT_SCHEDULE['discord.update_all_usernames'] = {
 }
 ```
 
-```eval_rst
+:::{note}
-.. note::
     You will have to add most the values for these settings, e.g. your Discord server ID (aka guild ID), later in the setup process.
 ```
 
@@ -48,8 +47,7 @@ Now retrieve the server ID [following this procedure.](https://support.discord.c
 
 Update your auth project's settings file, inputting the server ID as `DISCORD_GUILD_ID`
 
-```eval_rst
+:::{note}
-.. note::
     If you already have a Discord server skip the creation step, but be sure to retrieve the server ID
 ```
 
@@ -107,12 +105,11 @@ Second, it is possible to exclude Discord roles from being managed by Auth at al
 
 To exclude roles from being managed by Auth you only have to add them to the list of reserved group names in Group Management.
 
-```eval_rst
+:::{note}
-.. note::
     Role names on Discord are case sensitive, while reserved group names on Auth are not. Therefore reserved group names will cover all roles regardless of their case. For example if you have reserved the group name "alpha", then the Discord roles "alpha" and "Alpha" will both be persisted.
 ```
 
-```eval_rst
+```{eval-rst}
 .. seealso::
     For more information see :ref:`ref-reserved-group-names`.
 ```
@@ -123,11 +120,11 @@ The Discord service contains a number of tasks that can be run to manually perfo
 
 You can run any of these tasks from the command line. Please make sure that you are in your venv and then you can run this command from the same folder that your manage.py is located:
 
-```bash
+```shell
 celery -A myauth call discord.update_all_groups
 ```
 
-```eval_rst
+```{eval-rst}
 ======================== ====================================================
 Name                     Description
 ======================== ====================================================
@@ -138,8 +135,7 @@ Name                     Description
 ======================== ====================================================
 ```
 
-```eval_rst
+:::{note}
-.. note::
     Depending on how many users you have, running these tasks can take considerable time to finish. You can calculate roughly 1 sec per user for all tasks, except update_all, which needs roughly 3 secs per user.
 ```
 
@@ -147,7 +143,7 @@ Name                     Description
 
 You can configure your Discord services with the following settings:
 
-```eval_rst
+```{eval-rst}
 =================================== ============================================================================================= =======
 Name                                Description                                                                                   Default
 =================================== ============================================================================================= =======
@@ -168,7 +164,7 @@ Name                                Description
 
 To use this service, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/features/services/discourse.md

@@ -17,7 +17,7 @@ DISCOURSE_SSO_SECRET = ''
 
 ## Install Docker
 
-```bash
+```shell
 wget -qO- https://get.docker.io/ | sh
 ```
 
@@ -25,14 +25,14 @@ wget -qO- https://get.docker.io/ | sh
 
 ### Download Discourse
 
-```bash
+```shell
 mkdir /var/discourse
 git clone https://github.com/discourse/discourse_docker.git /var/discourse
 ```
 
 ### Configure
 
-```bash
+```shell
 cd /var/discourse
 cp samples/standalone.yml containers/app.yml
 nano containers/app.yml
@@ -68,7 +68,7 @@ Or any other port will do, if taken. Remember this number.
 
 ### Build and launch
 
-```bash
+```shell
 nano /etc/default/docker
 ```
 
@@ -80,13 +80,13 @@ Uncomment this line:
 
 Restart Docker:
 
-```bash
+```shell
     service docker restart
 ```
 
 Now build:
 
-```bash
+```shell
     ./launcher bootstrap app
     ./launcher start app
 ```
@@ -124,7 +124,7 @@ server {
 
 From the `/var/discourse` directory,
 
-```bash
+```shell
 ./launcher enter app
 rake admin:create
 ```
@@ -157,7 +157,7 @@ Finally run migrations and restart Gunicorn and Celery.
 
 To use this service, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/features/services/index.md

@@ -4,8 +4,7 @@
 
 ## Supported Services
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 discord
@@ -20,8 +19,7 @@
 
 ## Tools
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 nameformats

docs/features/services/mumble.md

@@ -2,12 +2,11 @@
 
 Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all the functionality and is easier to customize. And is better. I may be slightly biased.
 
-```eval_rst
+:::{note}
-.. note::
     Note that this guide assumes that you have installed Auth with the official :doc:`/installation/allianceauth` guide under ``/home/allianceserver`` and that it is called ``myauth``. Accordingly it assumes that you have a service user called ``allianceserver`` that is used to run all Auth services under supervisor.
 ```
 
-```eval_rst
+```{eval-rst}
 .. warning::
     This guide is currently for Ubuntu only.
 ```
@@ -18,17 +17,17 @@ Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all
 
 The mumble server package can be retrieved from a repository, which we need to add:
 
-```bash
+```shell
 sudo apt-add-repository ppa:mumble/release
 ```
 
-```bash
+```shell
 sudo apt-get update
 ```
 
 Now three packages need to be installed:
 
-```bash
+```shell
 sudo apt-get install python-software-properties mumble-server libqt5sql5-mysql
 ```
 
@@ -36,19 +35,19 @@ sudo apt-get install python-software-properties mumble-server libqt5sql5-mysql
 
 Next, we need to download the latest authenticator release from the [authenticator repository](https://gitlab.com/allianceauth/mumble-authenticator).
 
-```bash
+```shell
 git clone https://gitlab.com/allianceauth/mumble-authenticator /home/allianceserver/mumble-authenticator
 ```
 
 We will now install the authenticator into your Auth virtual environment. Please make sure to activate it first:
 
-```bash
+```shell
 source /home/allianceserver/venv/auth/bin/activate
 ```
 
 Install the python dependencies for the mumble authenticator. Note that this process can take 2-10 minutes to complete.
 
-```bash
+```shell
 pip install -r requirements.txt
 ```
 
@@ -66,7 +65,7 @@ GRANT ALL PRIVILEGES ON alliance_mumble . * TO 'allianceserver'@'localhost';
 
 Mumble ships with a configuration file that needs customization. By default it’s located at `/etc/mumble-server.ini`. Open it with your favorite text editor:
 
-```bash
+```shell
 sudo nano /etc/mumble-server.ini
 ```
 
@@ -90,7 +89,7 @@ Save and close the file.
 
 To get Mumble superuser account credentials, run the following:
 
-```bash
+```shell
 sudo dpkg-reconfigure mumble-server
 ```
 
@@ -98,7 +97,7 @@ Set the password to something you’ll remember and write it down. This is your
 
 Now restart the server to see the changes reflected.
 
-```bash
+```shell
 sudo service mumble-server restart
 ```
 
@@ -110,7 +109,7 @@ The ICE authenticator lives in the mumble-authenticator repository, cd to the di
 
 Make a copy of the default config:
 
-```bash
+```shell
 cp authenticator.ini.example authenticator.ini
 ```
 
@@ -124,19 +123,19 @@ Edit `authenticator.ini` and change these values:
 
 Test your configuration by starting it:
 
-```bash
+```shell
 python /home/allianceserver/mumble-authenticator/authenticator.py
 ```
 
 And finally ensure the allianceserver user has read/write permissions to the mumble authenticator files before proceeding:
 
-```bash
+```shell
 sudo chown -R allianceserver:allianceserver /home/allianceserver/mumble-authenticator
 ```
 
 The authenticator needs to be running 24/7 to validate users on Mumble. This can be achieved by adding a section to your auth project's supervisor config file like the following example:
 
-```text
+```ini
 [program:authenticator]
 command=/home/allianceserver/venv/auth/bin/python authenticator.py
 directory=/home/allianceserver/mumble-authenticator
@@ -151,7 +150,7 @@ priority=996
 
 In addition we'd recommend to add the authenticator to Auth's restart group in your supervisor conf. For that you need to add it to the group line as shown in the following example:
 
-```text
+```ini
 [group:myauth]
 programs=beat,worker,gunicorn,authenticator
 priority=999
@@ -159,7 +158,7 @@ priority=999
 
 To enable the changes in your supervisor configuration you need to restart the supervisor process itself. And before we do that we are shutting down the current Auth supervisors gracefully:
 
-```bash
+```shell
 sudo supervisor stop myauth:
 sudo systemctl restart supervisor
 ```
@@ -187,11 +186,11 @@ MUMBLE_URL = "mumble.example.com"
 
 Finally, run migrations and restart your supervisor to complete the setup:
 
-```bash
+```shell
 python /home/allianceserver/myauth/manage.py migrate
 ```
 
-```bash
+```shell
 supervisorctl restart myauth:
 ```
 
@@ -199,7 +198,7 @@ supervisorctl restart myauth:
 
 To use this service, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+
@@ -262,19 +261,19 @@ If Push to Talk is to your tastes, configure the suggestion as follows
 
 With the default configuration your mumble server is public. Meaning that everyone who has the address can at least connect to it and might also be able join all channels that don't have any permissions set (Depending on your ACL configured for the root channel). If you want only registered member being able to join your mumble, you have to set a server password. To do so open your mumble server configuration which is by default located at `/etc/mumble-server.ini`.
 
-```bash
+```shell
 sudo nano /etc/mumble-server.ini
 ```
 
 Now search for `serverpassword=` and set your password here. If there is no such line, simply add it.
 
-```text
+```ini
 serverpassword=YourSuperSecretServerPassword
 ```
 
 Save the file and restart your mumble server afterwards.
 
-```bash
+```shell
 sudo service mumble-server restart
 ```
 

docs/features/services/nameformats.md

@@ -6,7 +6,7 @@ Each service's username or nickname, depending on which the service supports, ca
 
 Currently the following services support custom name formats:
 
-```eval_rst
+```{eval-rst}
 +-------------+-----------+-------------------------------------+
 | Service     | Used with | Default Formatter                   |
 +=============+===========+=====================================+
@@ -30,8 +30,7 @@ Currently the following services support custom name formats:
 +-------------+-----------+-------------------------------------+
 ```
 
-```eval_rst
+:::{note}
-.. note::
     It's important to note here, before we get into what you can do with a name formatter, that before the generated name is passed off to the service to create an account it will be sanitized to remove characters (the letters and numbers etc.) that the service cannot support. This means that, despite what you configured, the service may display something different. It is up to you to test your formatter and understand how your format may be disrupted by a certain services sanitization function.
 ```
 
@@ -59,7 +58,7 @@ A more digestible documentation of string formatting in Python is available on t
 
 Some examples of strings you could use:
 
-```eval_rst
+```{eval-rst}
 +------------------------------------------+---------------------------+
 | Formatter                                | Result                    |
 +==========================================+===========================+
@@ -71,12 +70,12 @@ Some examples of strings you could use:
 +------------------------------------------+---------------------------+
 ```
 
-```eval_rst
+```{eval-rst}
 .. important::
     For most services, name formats only take effect when a user creates an account. This means if you create or update a name formatter it wont retroactively alter the format of users names. There are some exceptions to this where the service updates nicknames on a periodic basis. Check the service's documentation to see which of these apply.
 ```
 
-```eval_rst
+```{eval-rst}
 .. important::
     You must only create one formatter per service per state. E.g. don't create two formatters for Mumble for the Member state. In this case one of the formatters will be used and it may not be the formatter you are expecting.
 ```

docs/features/services/openfire.md

@@ -25,18 +25,18 @@ Openfire require a Java 8 runtime environment.
 
 Ubuntu 1804, 2004, 2204:
 
-```bash
+```shell
 sudo apt-get install openjdk-11-jre
 ```
 
 Centos 7:
 
-```bash
+```shell
 sudo yum install java-11-openjdk java-11-openjdk-devel
 ```
 
 Centos Stream 8, Stream 9:
-```bash
+```shell
 sudo dnf install java-11-openjdk java-11-openjdk-devel
 ```
 
@@ -51,7 +51,7 @@ On your PC, navigate to the [Ignite Realtime downloads section](https://www.igni
 Retrieve the file location by copying the URL from the “click here” link, depending on your browser you may have a Copy Link or similar option in your right click menu.
 
 In the console, ensure you’re in your user’s home directory:
-```bash
+```shell
 cd ~
 ```
 
@@ -59,14 +59,14 @@ Download and install the package, replacing the URL with the latest you got from
 
 Ubuntu 1804, 2004, 2204:
 
-```bash
+```shell
 wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_4.7.2_all.deb
 dpkg -i openfire_4.7.2_all.deb
 ```
 
 Centos 7, Stream 8, Stream 9:
 
-```bash
+```shell
 wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire-4.7.2-1.noarch.rpm
 yum install -y openfire-4.7.2-1.noarch.rpm
 ```
@@ -74,7 +74,7 @@ yum install -y openfire-4.7.2-1.noarch.rpm
 
 Performance is best when working from a SQL database. If you installed MySQL or MariaDB alongside your auth project, go ahead and create a database for Openfire:
 
-```bash
+```shell
 mysql -u root -p
 create database alliance_jabber;
 grant all privileges on alliance_jabber . * to 'allianceserver'@'localhost';
@@ -165,7 +165,7 @@ ACL is achieved by assigning groups to each of the three tiers: `Owners`, `Admin
 
 To use this service, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/features/services/permissions.md

@@ -6,7 +6,7 @@ In the past, access to services was dictated by a list of settings in `settings.
 
 Instead of granting access to services by the previous rigid structure, access to services is now granted by the built in Django permissions system. This means that service access can be more granular, allowing only certain states, certain groups, for instance Corp CEOs, or even individual user access to each enabled service.
 
-```eval_rst
+```{eval-rst}
 .. important::
     If you grant access to an individual user, they will have access to that service regardless of whether or not they are a member.
 ```
@@ -19,7 +19,7 @@ A user can be granted the same permission from multiple sources. e.g. they may h
 
 ## Removing access
 
-```eval_rst
+```{eval-rst}
 .. danger::
     Access removal is processed immediately after removing a permission from a user or group. If you remove access from a large group, such as Member, it will immediately remove all users from that service.
 ```

docs/features/services/phpbb3.md

@@ -34,7 +34,7 @@ DATABASES['phpbb3'] = {
 
 Create a database to install phpBB3 in.
 
-```bash
+```shell
 mysql -u root -p
 create database alliance_forum;
 grant all privileges on alliance_forum . * to 'allianceserver'@'localhost';
@@ -51,19 +51,19 @@ In the console, navigate to your user’s home directory: `cd ~`
 
 Now download using wget, replacing the URL with the URL for the package you just retrieved
 
-```bash
+```shell
 wget https://download.phpbb.com/pub/release/3.3/3.3.8/phpBB-3.3.8.zip
 ```
 
 This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
 
-```bash
+```shell
 unzip phpBB-3.3.8.zip
 ```
 
 Now we need to move this to our web directory. Usually `/var/www/forums`.
 
-```bash
+```shell
 mv phpBB3 /var/www/forums
 ```
 
@@ -72,7 +72,7 @@ The web server needs read/write permission to this folder
 Apache: `chown -R www-data:www-data /var/www/forums`
 Nginx: `chown -R nginx:nginx /var/www/forums`
 
-```eval_rst
+```{eval-rst}
 .. tip::
     Nginx: Some distributions use the ``www-data:www-data`` user:group instead of ``nginx:nginx``. If you run into problems with permissions try it instead.
 ..
@@ -157,7 +157,7 @@ phpBB will then write its own config file.
 
 Before users can see the forums, we need to remove the install directory
 
-```bash
+```shell
 rm -rf /var/www/forums/install
 ```
 
@@ -171,7 +171,7 @@ You can allow members to overwrite the portrait with a custom image if desired.
 
 Users generated via Alliance Auth do not have a default theme set. You will need to set this on the phpbb_users table in SQL
 
-```bash
+```shell
 mysql -u root -p
 use alliance_forum;
 alter table phpbb_users change user_style user_style int not null default 1
@@ -187,7 +187,7 @@ Once settings have been configured, run migrations and restart Gunicorn and Cele
 
 To use this service, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/features/services/smf.md

@@ -36,17 +36,17 @@ Using your browser, you can download the latest version of SMF to your desktop c
 
 Download using wget, replacing the URL with the URL for the package you just retrieved
 
-```bash
+```shell
 wget https://download.simplemachines.org/index.php?thanks;filename=smf_2-1-2_install.tar.gz
 ```
 
 This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
-```bash
+```shell
 unzip smf_2-1-2_install.zip
 ```
 
 Now we need to move this to our web directory. Usually `/var/www/forums`.
-```bash
+```shell
 mv smf /var/www/forums
 ````
 
@@ -55,7 +55,7 @@ The web server needs read/write permission to this folder
 Apache: `chown -R www-data:www-data /var/www/forums`
 Nginx: `chown -R nginx:nginx /var/www/forums`
 
-```eval_rst
+```{eval-rst}
 .. tip::
     Nginx: Some distributions use the ``www-data:www-data`` user:group instead of ``nginx:nginx``. If you run into problems with permissions try it instead.
 ..
@@ -139,7 +139,7 @@ Once settings are entered, apply migrations and restart Gunicorn and Celery.
 
 To use this service, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/features/services/teamspeak3.md

@@ -45,7 +45,7 @@ wget https://files.teamspeak-services.com/releases/server/3.13.7/teamspeak3-serv
 
 Now we need to extract the file.
 
-```bash
+```shell
 tar -xf teamspeak3-server_linux_amd64-3.13.7.tar.bz2
 ```
 
@@ -53,7 +53,7 @@ tar -xf teamspeak3-server_linux_amd64-3.13.7.tar.bz2
 
 TeamSpeak needs its own user.
 
-```bash
+```shell
 adduser --disabled-login teamspeak
 ```
 
@@ -61,7 +61,7 @@ adduser --disabled-login teamspeak
 
 Now we move the server binary somewhere more accessible and change its ownership to the new user.
 
-```bash
+```shell
 mv teamspeak3-server_linux_amd64 /usr/local/teamspeak
 chown -R teamspeak:teamspeak /usr/local/teamspeak
 ```
@@ -70,14 +70,14 @@ chown -R teamspeak:teamspeak /usr/local/teamspeak
 
 Now we generate a startup script so TeamSpeak comes up with the server.
 
-```bash
+```shell
 ln -s /usr/local/teamspeak/ts3server_startscript.sh /etc/init.d/teamspeak
 update-rc.d teamspeak defaults
 ```
 
 Finally we start the server.
 
-```bash
+```shell
 service teamspeak start
 ```
 
@@ -85,7 +85,7 @@ service teamspeak start
 
 Set your Teamspeak Serveradmin password to a random string
 
-```bash
+```shell
 ./ts3server_minimal_runscript.sh inifile=ts3server.ini serveradmin_password=pleasegeneratearandomstring
 
 ```
@@ -139,7 +139,7 @@ Then, in the top-right corner click, click on `Update TS3 Groups` to start the p
 
 Start a django shell with:
 
-```bash
+```shell
 python manage.py shell
 ```
 
@@ -180,7 +180,7 @@ This usually occurs if you've created a separate serverquery user to use with au
 
 To use and configure this service, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/features/services/xenforo.md

@@ -47,7 +47,7 @@ Once these are entered, run migrations and restart Gunicorn and Celery.
 
 To use this service, users will require some of the following.
 
-```eval_rst
+```{eval-rst}
 +---------------------------------------+------------------+--------------------------------------------------------------------------+
 | Permission                            | Admin Site       | Auth Site                                                                |
 +=======================================+==================+==========================================================================+

docs/index.md

@@ -7,8 +7,7 @@ Welcome to the official documentation for **Alliance Auth**!
 
 **Alliance Auth** is a web site that helps Eve Online organizations efficiently manage access to applications and external services.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 2
 :caption: Contents
 

docs/installation/allianceauth.md

@@ -2,10 +2,9 @@
 
 This document describes how to install **Alliance Auth** from scratch.
 
-```eval_rst
+:::{note}
-.. note::
 There are additional installation steps for activating services and apps that come with **Alliance Auth**. Please see the page for the respective service or apps in chapter :doc:`/features/index` for details.
-```
+:::
 
 ## Dependencies
 
@@ -28,234 +27,243 @@ To install on your favorite flavour of Linux, identify and install equivalent pa
 
 It is recommended to ensure your OS is fully up to date before proceeding. We may also add Package Repositories here, used later in the documentation.
 
-Ubuntu 1804, 2004, 2204:
+::::{tabs}
 
-```bash
+:::{group-tab} Ubuntu 2004, 2204
+
+```shell
 sudo apt-get update
 ```
 
-```bash
+```shell
 sudo apt-get upgrade
 ```
 
-```bash
+```shell
 sudo do-dist-upgrade
 ```
 
-CentOS 7:
+:::
+:::{group-tab} CentOS 7
 
-```bash
+```shell
 yum install epel-release
 ```
 
-```bash
+```shell
 sudo yum upgrade
 ```
 
-CentOS Stream 8:
+:::
+:::{group-tab} CentOS Stream 8
 
-```bash
+```shell
 sudo dnf config-manager --set-enabled powertools
 ```
 
-```bash
+```shell
 sudo dnf install epel-release epel-next-release
 ```
 
-```bash
+```shell
 sudo yum upgrade
 ```
 
-CentOS Stream 9:
+:::
+:::{group-tab} CentOS Stream 9
 
-```bash
+```shell
 sudo dnf config-manager --set-enabled crb
 ```
 
-```bash
+```shell
-dnf install epel-release epel-next-release
+sudo dnf install epel-release epel-next-release
 ```
 
-```bash
+```shell
 sudo yum upgrade
 ```
 
+:::
+::::
+
 ### Python
 
-Install Python 3.10 and related tools on your system.
+Install Python 3.11 and related tools on your system.
 
-Ubuntu 1804, 2004:
+::::{tabs}
 
-```bash
+:::{group-tab} Ubuntu 2004, 2204
+
+```shell
 sudo add-apt-repository ppa:deadsnakes/ppa
 ```
 
-```bash
+```shell
 sudo apt-get update
 ```
 
-```bash
+```shell
-sudo apt-get install python3.10 python3.10-dev python3.10-venv
+sudo apt-get install python3.11 python3.11-dev python3.11-venv
 ```
 
-Ubuntu 2204:
+:::
-
+:::{group-tab} CentOS 7, Stream 8, Stream 9
-```eval_rst
-.. note::
-    Ubuntu 2204 ships with Python 3.10 already, but some important tools are missing in the default installation.
-```
-
-```bash
-sudo apt-get install python3.10-dev python3.10-venv
-```
-
-CentOS 7:
 We need to build Python from source
 
-Centos Stream 8/9:
+```shell
-
-```eval_rst
-.. note::
-    A Python 3.9 Package is available for Stream 8 and 9. You _may_ use this instead of building your own package. But our documentation will assume Python3.10 and you may need to substitute as necessary
-    sudo dnf install python39 python39-devel
-```
-
-```bash
 cd ~
 ```
 
-```bash
+```shell
 sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
 ```
 
-```bash
+```shell
-wget https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tgz
+wget https://www.python.org/ftp/python/3.11.5/Python-3.11.5.tgz
 ```
 
-```bash
+```shell
-tar xvf Python-3.10.5.tgz
+tar xvf Python-3.11.5.tgz
 ```
 
-```bash
+```shell
-cd Python-3.10.5/
+cd Python-3.11.5/
 ```
 
-```bash
+```shell
 ./configure --enable-optimizations --enable-shared
 ```
 
-```bash
+```shell
 sudo make altinstall
 ```
 
+:::
+::::
+
 ### Database
 
-It's recommended to use a database service instead of SQLite. Many options are available, but this guide will use MariaDB.
+It's recommended to use a database service instead of SQLite. Many options are available, but this guide will use MariaDB 10.11
 
-```eval_rst
+::::{tabs}
-.. note::
-    Ubuntu distributions prior to 20.04 come with an older version of Maria DB, which is not compatible with **Alliance Auth**. You need Maria DB 10.3 or higher!
-    For 20.04 we still recommend to install Maria DB from the link below in order to get the newest stable version.
-    For 22.04 we recommend installing from the default Ubuntu distro, since it comes with the newest stable version.
-```
 
-Ubuntu 1804, 2004:
+:::{group-tab} Ubuntu 2004, 2204
+Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=20.04+%22focal%22&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
 
-```eval_rst
+```shell
-.. warning::
-    Please follow these steps to update MariaDB
-    https://mariadb.org/download/?t=repo-config&d=20.04+%22focal%22&v=10.6&r_m=osuosl
-```
-
-Ubuntu 1804, 2004, 2204
-
-```bash
 sudo apt-get install mariadb-server mariadb-client libmysqlclient-dev
 ```
 
-CentOS 7:
+:::
+:::{group-tab} CentOS 7
+Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=CentOS+7&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
 
-```eval_rst
+```shell
-.. warning::
-    Please follow these steps to update MariaDB
-    https://mariadb.org/download/?t=repo-config&d=CentOS+7+%28x86_64%29&v=10.6&r_m=osuosl
-```
-
-```bash
 sudo yum install MariaDB-server MariaDB-client MariaDB-devel MariaDB-shared
 ```
 
-CentOS Stream 8/9:
+:::
+:::{group-tab} CentOS Stream 8
+Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=CentOS+Stream&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
 
-```eval_rst
+```shell
-.. note::
-    We recommend using the built in AppStream, as they are maintained by CentOS. Currently an AppStream is not available for 10.6
-```
-
-```bash
-sudo dnf module enable mariadb:10.5
-```
-
-```bash
 sudo dnf install mariadb mariadb-server mariadb-devel
 ```
 
-```bash
+:::
-sudo systemctl enable mariadb
+:::{group-tab} CentOS Stream 9
+Follow the instructions at <https://mariadb.org/download/?t=repo-config&d=CentOS+Stream&v=10.11&r_m=osuosl> to add the MariaDB repository to your host.
+
+```shell
+sudo dnf install mariadb mariadb-server mariadb-devel
 ```
 
-```bash
+:::
-sudo systemctl start mariadb
+::::
-```
 
-```eval_rst
+:::::{important}
-.. important::
+::::{tabs}
-    If you don't plan on running the database on the same server as auth you still need to install the ``libmysqlclient-dev`` package on Ubuntu or ``mariadb-devel`` package on CentOS.
+:::{group-tab} Ubuntu 2004, 2204
-```
+If you don't plan on running the database on the same server as auth you still need to install the `libmysqlclient-dev` package
+:::
+:::{group-tab} CentOS 7
+If you don't plan on running the database on the same server as auth you still need to install the `mariadb-devel` package
+:::
+:::{group-tab} CentOS Stream 8
+If you don't plan on running the database on the same server as auth you still need to install the `mariadb-devel` package
+:::
+:::{group-tab} CentOS Stream 9
+If you don't plan on running the database on the same server as auth you still need to install the `mariadb-devel` package
+:::
+::::
+:::::
 
 ### Redis and Other Tools
 
 A few extra utilities are also required for installation of packages.
 
-Ubuntu 1804, 2004, 2204:
+::::{tabs}
 
-```bash
+:::{group-tab} Ubuntu 2004, 2204
+
+```shell
 sudo apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev build-essential pkg-config
 ```
 
-CentOS 7:
+:::
+:::{group-tab} CentOS 7
 
-```bash
+```shell
 sudo yum install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget pkg-config
 ```
 
-```bash
+```shell
 sudo systemctl enable redis.service
 ```
 
-```bash
+```shell
 sudo systemctl start redis.service
 ```
 
-CentOS Stream 8, Stream 9:
+:::
+:::{group-tab} CentOS Stream 8
 
-```bash
+```shell
 sudo dnf install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
 ```
 
-```bash
+```shell
 sudo systemctl enable redis.service
 ```
 
-```bash
+```shell
 sudo systemctl start redis.service
 ```
 
+:::
+:::{group-tab} CentOS Stream 9
+
+```shell
+sudo dnf install gcc gcc-c++ unzip git redis curl bzip2-devel openssl-devel libffi-devel wget
+```
+
+```shell
+sudo systemctl enable redis.service
+```
+
+```shell
+sudo systemctl start redis.service
+```
+
+:::
+::::
+
 ## Database Setup
 
 Alliance Auth needs a MySQL user account and database. Open an SQL shell with
 
-```bash
+```shell
 sudo mysql -u root
 ```
 
@@ -271,22 +279,24 @@ Once your database is set up, you can leave the SQL shell with `exit`.
 
 Add timezone tables to your mysql installation:
 
-```bash
+```shell
 mysql_tzinfo_to_sql /usr/share/zoneinfo | sudo mysql -u root mysql
 ```
 
-```eval_rst
+:::{note}
-.. note::
+You may see errors when you add the timezone tables. To make sure that they were correctly added run the following commands and check for the ``time_zone`` tables
-    You may see errors when you add the timezone tables. To make sure that they were correctly added run the following commands and check for the ``time_zone`` tables::
 
+```bash
 mysql -u root -p
 use mysql;
 show tables;
 ```
 
+:::
+
 Close the SQL shell and secure your database server with this command:
 
-```bash
+```shell
 mysql_secure_installation
 ```
 
@@ -295,86 +305,96 @@ mysql_secure_installation
 ### User Account
 
 For security and permissions, it’s highly recommended you create a separate user to install auth under. Do not log in as this account.
+::::{tabs}
 
-Ubuntu 1804, 2004, 2204:
+:::{group-tab} Ubuntu 2004, 2204
 
-```bash
+```shell
-sudo adduser --disabled-login allianceserver
-```
-
-CentOS 7, Stream 8, Stream 9:
-
-```bash
 sudo useradd -s /bin/bash allianceserver
 ```
 
-```bash
+:::
+:::{group-tab} CentOS 7
+
+```shell
 sudo passwd -l allianceserver
 ```
 
+:::
+:::{group-tab} CentOS Stream 8
+
+```shell
+sudo passwd -l allianceserver
+```
+
+:::
+:::{group-tab} CentOS Stream 9
+
+```shell
+sudo passwd -l allianceserver
+```
+
+:::
+::::
+
 ### Prepare Directories
 
-```bash
+```shell
 sudo mkdir -p /var/www/myauth/static
 ```
 
-```bash
+```shell
 sudo chown -R allianceserver:allianceserver /var/www/myauth/static/
 ```
 
-```eval_rst
+:::{warning}
-.. note::
+When installing and performing maintenance on Alliance Auth, virtual environments and python packages, _sudo_ means _superuser_ _do_, this will not use your venv or your allianceserver user  and will routinely break your permission structure.
-    When installing and performing maintenance on Alliance Auth, using the allianceserver user will greatly simplify permission management::
 
+Only use sudo for _system_ management or if you are unsure, when explicitly instructed to do so.
+
+```shell
 sudo su allianceserver
 ```
 
+:::
+
 ### Virtual Environment
 
 Switch to the allianceserver user.
 
-```bash
+```shell
 sudo su allianceserver
 ```
 
 And switch to it's home directory:
 
-```bash
+```shell
-cd
+cd ~
-```
-
-```eval_rst
-.. note::
-    In general using the allianceserver user will greatly simplify permission management, when installing and performing maintenance on Alliance Auth.
 ```
 
 Create a Python virtual environment and put it somewhere convenient (e.g. `/home/allianceserver/venv/auth/`)
 
-```eval_rst
+:::{note}
-.. note::
 Your python3.x command/version may vary depending on your installed python version.
+:::
+
+```shell
+python3.11 -m venv /home/allianceserver/venv/auth/
 ```
 
-```bash
+:::{tip}
-python3.10 -m venv /home/allianceserver/venv/auth/
+A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the Python_ docs. <https://docs.python.org/3/library/venv.html>
-```
+:::
-
-```eval_rst
-.. tip::
-    A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the Python_ docs.
-.. _Python: https://docs.python.org/3/library/venv.html
-```
 
 Activate the virtual environment with (Note the `/bin/activate` on the end of the path):
 
-```bash
+```shell
 source /home/allianceserver/venv/auth/bin/activate
 ```
 
-```eval_rst
+:::{hint}
-.. hint::
 Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first. When finished, deactivate it with the ``deactivate`` command.
-```
+:::
 
 ### Eve Online SSO
 
@@ -386,22 +406,21 @@ As **callback URL** you want to define the URL of your Alliance Auth site plus t
 
 ### Alliance Auth Project
 
-```eval_rst
+:::{warning}
-.. warning::
 Before installing any Python packages please double-check that you have activated in the virtual environment. This is usually indicated by your command line in the terminal starting with: `(auth)`.
-```
+:::
 
 #### Install Python packages
 
 Update & install basic tools before installing further Python packages:
 
-```bash
+```shell
 pip install -U pip setuptools wheel
 ```
 
 You can install **Alliance Auth** with the following command. This will install AA, AA's Python dependencies, superlance for memory monitoring and gunicorn as a wsgi server
 
-```bash
+```shell
 pip install allianceauth superlance gunicorn
 ```
 
@@ -409,13 +428,13 @@ pip install allianceauth superlance gunicorn
 
 Now you need to create the Django project that will run **Alliance Auth**. Ensure you are in the allianceserver home directory by issuing:
 
-```bash
+```shell
 cd /home/allianceserver
 ```
 
 The following command bootstraps a Django project which will run your **Alliance Auth** instance. You can rename it from `myauth` to anything you'd like. Note that this name is shown by default as the site name but that can be changed later.
 
-```bash
+```shell
 allianceauth start myauth
 ```
 
@@ -423,7 +442,7 @@ allianceauth start myauth
 
 Your settings file needs configuring:
 
-```bash
+```shell
 nano myauth/myauth/settings/local.py
 ```
 
@@ -439,34 +458,36 @@ nano myauth/myauth/settings/local.py
 
 Django needs to setup the database before it can start.
 
-```bash
+```shell
 python /home/allianceserver/myauth/manage.py migrate
 ```
 
 Now we need to round up all the static files required to render templates. Make a directory to serve them from and populate it.
 
-```bash
+```shell
 python /home/allianceserver/myauth/manage.py collectstatic --noinput
 ```
 
 Check to ensure your settings are valid.
 
-```bash
+```shell
 python /home/allianceserver/myauth/manage.py check
 ```
 
-```eval_rst
+:::{hint}
-.. hint::
 If you are using root, ensure the allianceserver user has read/write permissions to this directory before proceeding::
 
+```
 chown -R allianceserver:allianceserver /home/allianceserver/myauth
 ```
 
+:::
+
 #### Setup superuser
 
 Before using your auth site, it is essential to create a superuser account. This account will have all permissions in Alliance Auth. It's OK to use this as your personal auth account.
 
-```bash
+```shell
 python /home/allianceserver/myauth/manage.py createsuperuser
 ```
 
@@ -488,72 +509,117 @@ The default configuration is good enough for most installations. Additional info
 
 [Supervisor](http://supervisord.org/) is a process watchdog service: it makes sure other processes are started automatically and kept running. It can be used to automatically start the WSGI server and Celery workers for background tasks.
 
-```eval_rst
+:::{note}
-.. note::
     You will need to exit the allianceserver user back to a user with sudo capabilities to install supervisor::
 
+```bash
       exit
 ```
 
-Ubuntu 1804, 2004, 2204:
+:::
 
-```bash
+::::{tabs}
+
+:::{group-tab} Ubuntu 2004, 2204
+
+```shell
 sudo apt-get install supervisor
 ```
 
-CentOS 7:
+:::
+:::{group-tab} CentOS 7
 
-```bash
+```shell
 sudo dnf install supervisor
 ```
 
-```bash
+```shell
 sudo systemctl enable supervisord.service
 ```
 
-```bash
+```shell
 sudo systemctl start supervisord.service
 ```
 
-CentOS Stream 8, Stream 9:
+:::
+:::{group-tab} CentOS Stream 8
 
-```bash
+```shell
 sudo dnf install supervisor
 ```
 
-```bash
+```shell
 sudo systemctl enable supervisord.service
 ```
 
-```bash
+```shell
 sudo systemctl start supervisord.service
 ```
 
+:::
+:::{group-tab} CentOS Stream 9
+
+```shell
+sudo dnf install supervisor
+```
+
+```shell
+sudo systemctl enable supervisord.service
+```
+
+```shell
+sudo systemctl start supervisord.service
+```
+
+:::
+::::
+
 Once installed, it needs a configuration file to know which processes to watch. Your Alliance Auth project comes with a ready-to-use template which will ensure the Celery workers, Celery task scheduler and Gunicorn are all running.
+::::{tabs}
 
-Ubuntu 1804, 2004:
+:::{group-tab} Ubuntu 2004, 2204
 
-```bash
+```shell
 ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf
 ```
 
-CentOS:
+:::
+:::{group-tab} CentOS 7
 
-```bash
+```shell
 sudo ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
 ```
 
+:::
+:::{group-tab} CentOS Stream 8
+
+```shell
+sudo ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
+```
+
+:::
+:::{group-tab} CentOS Stream 9
+
+```shell
+sudo ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
+```
+
+:::
+::::
+
 Activate it with `sudo supervisorctl reload`.
 
 You can check the status of the processes with `sudo supervisorctl status`. Logs from these processes are available in `/home/allianceserver/myauth/log` named by process.
 
-```eval_rst
+:::{note}
-.. note::
 Any time the code or your settings change you'll need to restart Gunicorn and Celery. ::
 
+```shell
 sudo supervisorctl restart myauth:
 ```
 
+:::
+
 ## Web server
 
 Once installed, decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md) and follow the respective guide.
@@ -566,42 +632,42 @@ Periodically [new releases](https://gitlab.com/allianceauth/allianceauth/tags) a
 
 To update your install, swap to your allianceserver user
 
-```bash
+```shell
 sudo su allianceserver
 ```
 
 Activate your virtual environment
 
-```bash
+```shell
 source /home/allianceserver/venv/auth/bin/activate
 ```
 
 and update with:
 
-```bash
+```shell
 pip install -U allianceauth
 ```
 
 Some releases come with changes to the base settings. Update your project's settings with:
 
-```bash
+```shell
 allianceauth update /home/allianceserver/myauth
 ```
 
 Some releases come with new or changed models. Update your database to reflect this with:
 
-```bash
+```shell
 python /home/allianceserver/myauth/manage.py migrate
 ```
 
 Finally, some releases come with new or changed static files. Run the following command to update your static files folder:
 
-```bash
+```shell
 python /home/allianceserver/myauth/manage.py collectstatic --noinput
 ```
 
 Always restart AA, Celery and Gunicorn after updating:
 
-```bash
+```shell
 supervisorctl restart myauth:
 ```

docs/installation/apache.md

@@ -9,25 +9,25 @@ If you're using a small VPS to host services with very limited memory, consider
 ## Installation
 
 Ubuntu 1804, 2004:
-```bash
+```shell
 apt-get install apache2
 ```
 
 CentOS 7:
-```bash
+```shell
 yum install httpd
 ```
 Centos Stream 8, Stream 9
-```bash
+```shell
 dnf install httpd
 ```
 
 CentOS 7, Stream 8, Stream 9
-```bash
+```shell
 systemctl enable httpd
 ```
 
-```bash
+```shell
 systemctl start httpd
 ```
 ## Configuration
@@ -49,7 +49,7 @@ A virtual host for auth need only proxy requests to your WSGI server (Gunicorn i
 ### Ubuntu
 
 To proxy and modify headers a few mods need to be enabled.
-```bash
+```shell
 a2enmod proxy
 a2enmod proxy_http
 a2enmod headers
@@ -57,7 +57,7 @@ a2enmod headers
 
 Create a new config file for auth e.g. `/etc/apache2/sites-available/myauth.conf` and fill out the virtual host configuration. To enable your config use `a2ensite myauth.conf` and then reload apache with `service apache2 reload`.
 
-```eval_rst
+```{eval-rst}
 .. warning::
     In some scenarios, the Apache default page is still enabled. To disable it use::
       a2dissite 000-default.conf

docs/installation/gunicorn.md

@@ -6,15 +6,13 @@ If you find Apache's `mod_wsgi` to be a headache or want to use NGINX (or some o
 
 Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html).
 
-```eval_rst
+:::{note}
-.. note::
     The page contains additional steps on how to setup and configure Gunicorn that are not required for users who decide to stick with the default Gunicorn configuration as described in the main installation guide for AA.
 ```
 
 ## Setting up Gunicorn
 
-```eval_rst
+:::{note}
-.. note::
     If you're using a virtual environment, activate it now::
       sudo su allianceserver
       source /home/allianceserver/venv/auth/bin/activate
@@ -22,7 +20,7 @@ Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html
 
 Install Gunicorn using pip
 
-```bash
+```shell
 pip install gunicorn
 ```
 
@@ -38,7 +36,7 @@ If you are following this guide, we already use [Supervisor](allianceauth.md#sup
 
 You'll want to edit `/etc/supervisor/conf.d/myauth.conf` (or whatever you want to call the config file)
 
-```text
+```ini
 [program:gunicorn]
 user = allianceserver
 directory=/home/allianceserver/myauth/
@@ -97,6 +95,6 @@ Any web server capable of proxy passing should be able to sit in front of Gunico
 
 In the past when you made changes you restarted the entire Apache server. This is no longer required. When you update or make configuration changes that ask you to restart Apache, instead you can just restart Gunicorn:
 
-```bash
+```shell
 supervisorctl restart myauth:gunicorn
 ```

docs/installation/index.md

@@ -4,8 +4,7 @@ This chapter contains the main installation guides for **Alliance Auth**.
 
 In addition to main guide for installation Alliance Auth you also find guides for configuring web servers (Apache, NGINX) and the recommended WSGI server (Gunicorn).
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 allianceauth

docs/installation/nginx.md

@@ -14,7 +14,7 @@ If you're converting from Apache, here are some things to consider.
 
 Nginx is lightweight for a reason. It doesn't try to do everything internally and instead concentrates on just being a good HTTP server. This means that, unlike Apache, it won't automatically run PHP scripts via mod_php and doesn't have an internal WSGI server like mod_wsgi. That doesn't mean that it can't, just that it relies on external processes to run these instead. This might be good or bad depending on your outlook. It's good because it allows you to segment your applications, restarting Alliance Auth wont impact your PHP applications. On the other hand it means more config and more management of services. For some people it will be worth it, for others losing the centralised nature of Apache may not be worth it.
 
-```eval_rst
+```{eval-rst}
 +-----------+----------------------------------------+
 | Apache    | Nginx Replacement                      |
 +===========+========================================+
@@ -33,7 +33,7 @@ Install Nginx via your preferred package manager or other method. If you need he
 
 Nginx needs to be able to read the folder containing your auth project's static files. `chown -R nginx:nginx /var/www/myauth/static`.
 
-```eval_rst
+```{eval-rst}
 .. tip::
     Some specific distros may use ``www-data:www-data`` instead of ``nginx:nginx``, causing static files (images, stylesheets etc) not to appear. You can confirm what user Nginx will run under by checking either its base config file ``/etc/nginx/nginx.conf`` for the "user" setting, or once Nginx has started ``ps aux | grep nginx``.
     Adjust your chown commands to the correct user if needed.
@@ -45,24 +45,24 @@ You will need to have [Gunicorn](gunicorn.md) or some other WSGI server setup fo
 ## Install
 
 Ubuntu 1804, 2004, 2204:
-```bash
+```shell
 sudo apt-get install nginx
 ```
 
 CentOS 7
-```bash
+```shell
 sudo yum install nginx
 ```
 
 CentOS Stream 8, Stream 9:
-```bash
+```shell
 sudo dnf install nginx
 ```
 
 Create a config file in `/etc/nginx/sites-available` (`/etc/nginx/conf.d` on CentOS) and call it `alliance-auth.conf` or whatever your preferred name is.
 
 Create a symbolic link to enable the site (not needed on CentOS):
-```bash
+```shell
 ln -s /etc/nginx/sites-available/alliance-auth.conf /etc/nginx/sites-enabled/
 ```
 

docs/installation/upgrade_python.md

@@ -4,8 +4,7 @@ This guide describes how to upgrade an existing Alliance Auth (AA) installation
 
 This guide shares many similarities with the Alliance Auth install guide, but it is targeted towards existing installs needing to update.
 
-```eval_rst
+:::{note}
-.. note::
     This guide will upgrade the software components only but not change any data or configuration.
 ```
 
@@ -16,20 +15,19 @@ To run AA with a newer Python 3 version than your system's default you need to i
 To install other Python versions than those included with your distribution, you need to add a new installation repository. Then you can install the specific Python 3 to your system.
 
 Ubuntu 1804, 2004:
-```eval_rst
+:::{note}
-.. note::
     Ubuntu 2204 ships with Python 3.10 already
 ```
 
-```bash
+```shell
 sudo add-apt-repository ppa:deadsnakes/ppa
 ```
 
-```bash
+```shell
 sudo apt-get update
 ```
 
-```bash
+```shell
 sudo apt-get install python3.10 python3.10-dev python3.10-venv
 ```
 
@@ -37,37 +35,36 @@ CentOS 7:
 We need to build Python from source
 
 Centos Stream 8/9:
-```eval_rst
+:::{note}
-.. note::
     A Python 3.9 Package is available for Stream 8 and 9. You _may_ use this instead of building your own package. But our documentation will assume Python3.10 and you may need to substitute as neccessary
     sudo dnf install python39 python39-devel
 ```
 
-```bash
+```shell
 cd ~
 ```
 
-```bash
+```shell
 sudo yum install gcc openssl-devel bzip2-devel libffi-devel wget
 ```
 
-```bash
+```shell
 wget https://www.python.org/ftp/python/3.10.5/Python-3.10.5.tgz
 ```
 
-```bash
+```shell
 tar xvf Python-3.10.5.tgz
 ```
 
-```bash
+```shell
 cd Python-3.10.5/
 ```
 
-```bash
+```shell
 ./configure --enable-optimizations --enable-shared
 ```
 
-```bash
+```shell
 sudo make altinstall
 ```
 ## Preparing your venv
@@ -76,8 +73,7 @@ Before updating your venv it is important to make sure that your current install
 
 Start by navigating to your main project folder (the one that has `manage.py` in it). If you followed the default installation the path is: `/home/allianceserver/myauth`
 
-```eval_rst
+:::{note}
-.. note::
     If you installed Alliance Auth under the allianceserver user, as reccommended. Remember to switch users for easier permission management::
 
       sudo su allianceserver
@@ -85,7 +81,7 @@ Start by navigating to your main project folder (the one that has `manage.py` in
 
 Activate your venv:
 
-```bash
+```shell
 source /home/allianceserver/venv/auth/bin/activate
 ```
 
@@ -93,23 +89,23 @@ source /home/allianceserver/venv/auth/bin/activate
 
 Make sure to upgrade AA to the newest version:
 
-```bash
+```shell
 pip install -U allianceauth
 ```
 
 Run migrations and collectstatic.
 
-```bash
+```shell
 python manage.py migrate
 ```
 
-```bash
+```shell
 python manage.py collectstatic
 ```
 
 Restart your AA supervisor:
 
-```bash
+```shell
 supervisorctl restart myauth:
 ```
 
@@ -119,23 +115,23 @@ You also need to upgrade all additional apps to their newest version that you ha
 
 If you unsure which apps you have installed from repos check `INSTALLED_APPS` in your settings. Alternatively run this command to get a list all apps in your venv.
 
-```bash
+```shell
 pip list
 ```
 
 Repeat as needed for your apps
 
-```bash
+```shell
 pip install -U APP_NAME
 ```
 
 Make sure to run migrations and collect static files for all upgraded apps.
 
-```bash
+```shell
 python manage.py migrate
 ```
 
-```bash
+```shell
 python manage.py collectstatic
 ```
 ### Restart and final check
@@ -144,13 +140,13 @@ Do a final restart of your AA supervisors and make sure your installation is sti
 
 For a final check that they are no issues - e.g. any outstanding migrations - run this command:
 
-```bash
+```shell
 python manage.py check
 ```
 
 If you get the following result you are good to go. Otherwise make sure to fix any issues first before proceeding.
 
-```bash
+```shell
 System check identified no issues (0 silenced).
 ```
 
@@ -160,7 +156,7 @@ Make sure you are in your venv!
 
 First we create a list of all installed packages in your venv. You can use this list later as reference to see what packages should be installed.
 
-```bash
+```shell
 pip freeze > requirements.txt
 ```
 
@@ -169,29 +165,28 @@ At this point we recommend creating a list of the additional packages that you n
 - Community AA apps (e.g. aa-structures)
 - Additional tools you are using (e.g. flower, django-extensions)
 
-```eval_rst
+```{eval-rst}
 .. hint::
     While `requirements.txt` will contain a complete list of your packages, it will also contain many packages that are automatically installed as dependencies and don't need be manually reinstalled.
 ```
 
-```eval_rst
+:::{note}
-.. note::
     Some guide on the Internet will suggest to use use the requirements.txt file to recreate a venv. This is indeed possible, but only works if all packages can be installed from PyPI. Since most community apps are installed directly from repos this guide will not follow that approach.
 ```
 
 Leave the venv and shutdown all AA services:
 
-```bash
+```shell
 deactivate
 ```
 
-```bash
+```shell
 supervisorctl stop myauth:
 ```
 
 Rename and keep your old venv so we have a fallback in case of some unforeseeable issues:
 
-```bash
+```shell
 mv /home/allianceserver/venv/auth /home/allianceserver/venv/auth_old
 ```
 
@@ -199,11 +194,11 @@ mv /home/allianceserver/venv/auth /home/allianceserver/venv/auth_old
 
 Now let's create our new venv with Python 3.10 and activate it:
 
-```bash
+```shell
 python3.10 -m venv /home/allianceserver/venv/auth
 ```
 
-```bash
+```shell
 source /home/allianceserver/venv/auth/bin/activate
 ```
 
@@ -213,17 +208,17 @@ Now we need to reinstall all packages into your new venv.
 
 ### Install basic packages
 
-```bash
+```shell
 pip install -U pip setuptools wheel
 ```
 
 ### Installing AA & Gunicorn
 
-```bash
+```shell
 pip install allianceauth
 ```
 
-```bash
+```shell
 pip install gunicorn
 ```
 
@@ -235,13 +230,13 @@ Use the list of packages you created earlier as a checklist. Alternatively you u
 
 To check whether you are missing any apps you can also run the check command:
 
-```bash
+```shell
 python manage.py check
 ```
 
 Note: In case you forget to install an app you will get this error
 
-```bash
+```shell
 ModuleNotFoundError: No module named 'xyz'
 ```
 
@@ -251,7 +246,7 @@ Note that you should not need to run any migrations unless you forgot to upgrade
 
 After you have completed installing all packages just start your AA supervisor again.
 
-```bash
+```shell
 supervisorctl start myauth:
 ```
 
@@ -263,7 +258,7 @@ In case you run into any major issue you can always switch back to your initial
 
 Before you start double-check that you still have your old venv for auth:
 
-```bash
+```shell
 ls /home/allianceserver/venv/auth /home/allianceserver/venv
 ```
 
@@ -274,18 +269,18 @@ If the output shows these two folders you should be safe to proceed:
 
 Run these commands to remove your current venv and switch back to the old venv for auth:
 
-```bash
+```shell
 supervisorctl stop myauth:
 ```
 
-```bash
+```shell
 rm -rf /home/allianceserver/venv/auth
 ```
 
-```bash
+```shell
 mv /home/allianceserver/venv/auth_old /home/allianceserver/venv/auth
 ```
 
-```bash
+```shell
 supervisorctl start myauth:
 ```

docs/maintenance/apps.md

@@ -13,8 +13,7 @@ Your auth project is just a regular Django project - you can add in [other Djang
 
 The following instructions will explain how you can remove an app properly fom your Alliance Auth installation.
 
-```eval_rst
+:::{note}
-.. note::
     We recommend following these instructions to avoid dangling foreign keys or orphaned Python packages on your system, which might cause conflicts with other apps down the road.
 
 ```
@@ -27,7 +26,7 @@ First, we want to remove the app related tables from the database.
 
 Let's first try the automatic approach by running the following command:
 
-```sh
+```shell
 python manage.py migrate appname zero
 ```
 
@@ -39,32 +38,32 @@ If that did not work and you got error messages, you will need to remove the tab
 
 First, tell Django that these migrations are no longer in effect (note the additional `--fake`):
 
-```sh
+```shell
 python manage.py migrate appname zero --fake
 ```
 
 Then, open the mysql tool and connect to your Alliance Auth database:
 
-```sh
+```shell
 sudo mysql -u root
 use alliance_auth;
 ```
 
 Next disable foreign key check. This makes it much easier to drop tables in any order.
 
-```sh
+```shell
 SET FOREIGN_KEY_CHECKS=0;
 ```
 
 Then get a list of all tables. All tables belonging to the app in question will start with `appname_`.
 
-```sh
+```shell
 show tables;
 ```
 
 Now, drop the tables from the app one by one like so:
 
-```sh
+```shell
 drop table appname_model_1;
 drop table appname_model_2;
 ...
@@ -72,7 +71,7 @@ drop table appname_model_2;
 
 And finally, but very importantly, re-enable foreign key checks again and then exit:
 
-```sh
+```shell
 SET FOREIGN_KEY_CHECKS=1;
 exit;
 ```
@@ -85,7 +84,7 @@ Once the tables have been removed, you you can remove the app from Alliance Auth
 
 Finally, we want to remove the app's Python package. For that run the following command:
 
-```sh
+```shell
 pip uninstall app-package-name
 ```
 

docs/maintenance/index.md

@@ -2,8 +2,7 @@
 
 In the maintenance chapter you find details about where important log files are found, how you can customize your AA installation and how to solve common issues.
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 apps

docs/maintenance/troubleshooting.md

@@ -24,7 +24,7 @@ Make sure the background processes are running: `supervisorctl status myauth:`.
 
 Stop celery workers with `supervisorctl stop myauth:worker` then clear the queue:
 
-```bash
+```shell
     redis-cli FLUSHALL
     celery -A myauth worker --purge
 ```
@@ -49,7 +49,7 @@ Gunicorn needs to have context for its running location, `/home/alllianceserver/
 
 Migrations may about with the following error message:
 
-```bash
+```shell
 Specified key was too long; max key length is 767 bytes
 ```
 

docs/maintenance/tuning/celery.md

@@ -1,6 +1,6 @@
 # Celery
 
-```eval_rst
+```{eval-rst}
 .. hint::
     Most tunings will require a change to your supervisor configuration in your `supervisor.conf` file. Note that you need to restart the supervisor daemon in order for any changes to take effect. And before restarting the daemon you may want to make sure your supervisors stop gracefully:(Ubuntu):
 
@@ -14,13 +14,13 @@
 
 By default task logging is deactivated. Enabling task logging allows you to monitor what tasks are doing in addition to getting all warnings and error messages. To enable info logging for tasks add the following to the command configuration of your worker in the `supervisor.conf` file:
 
-```text
+```ini
 -l info
 ```
 
 Full example:
 
-```text
+```ini
 command=/home/allianceserver/venv/auth/bin/celery -A myauth worker -l info
 ```
 
@@ -28,7 +28,7 @@ command=/home/allianceserver/venv/auth/bin/celery -A myauth worker -l info
 
 Celery workers often have memory leaks and will therefore grow in size over time. While the Alliance Auth team is working hard to ensure Auth is free of memory leaks some may still be cause by bugs in different versions of libraries or community apps. It is therefore good practice to enable features that protect against potential memory leaks.
 
-```eval_rst
+```{eval-rst}
 .. hint::
     The 256 MB limit is just an example and should be adjusted to your system configuration. We would suggest to not go below 128MB though, since new workers start with around 80 MB already. Also take into consideration that this value is per worker and that you may have more than one worker running in your system.
 ```
@@ -42,13 +42,13 @@ This is not a built in feature and requires the 3rd party extension [superlance]
 
 To setup install superlance into your venv with:
 
-```bash
+```shell
 pip install superlance
 ```
 
 You can then add `memmon` to your `supervisor.conf`:
 
-```text
+```ini
 [eventlistener:memmon]
 command=/home/allianceserver/venv/auth/bin/memmon -p worker=256MB
 directory=/home/allianceserver/myauth
@@ -67,7 +67,7 @@ Celery tasks are designed to run concurrently, so one obvious way to increase ta
 
 The easiest way to increate throughput can be achieved by increasing the `numprocs` parameter of the suprvisor process. For example:
 
-```text
+```ini
 [program:worker]
 ...
 numprocs=2
@@ -83,14 +83,14 @@ numprocs * concurency = workers
 
 increasing this number will require a modification to the memmon settings as each `numproc` worker will get a unique name for example with `numproc=3`
 
-```text
+```ini
 [eventlistener:memmon]
 ...
 command=... -p worker_00=256MB -p worker_01=256MB -p worker_02=256MB
 ...
 ```
 
-```eval_rst
+```{eval-rst}
 .. hint::
     You will want to experiment with different settings to find the optimal. One way to generate task load and verify your configuration is to run a model update with the following command:
 
@@ -104,11 +104,11 @@ command=... -p worker_00=256MB -p worker_01=256MB -p worker_02=256MB
 
 This can be achieved by the setting the concurrency parameter of the celery worker to a higher number. For example:
 
-```text
+```ini
 --concurrency=10
 ```
 
-```eval_rst
+```{eval-rst}
 .. hint::
     The optimal number will hugely depend on your individual system configuration and you may want to experiment with different settings to find the optimal. One way to generate task load and verify your configuration is to run a model update with the following command:
 
@@ -118,7 +118,7 @@ This can be achieved by the setting the concurrency parameter of the celery work
 
 ```
 
-```eval_rst
+```{eval-rst}
 .. hint::
     The optimal number of concurrent workers will be different for every system and we recommend experimenting with different figures to find the optimal for your system. Note, that the example of 10 threads is conservative and should work even with smaller systems.
 ```

docs/maintenance/tuning/gunicorn.md

@@ -8,6 +8,6 @@ The number you set this to will depend on your own server environment, how many
 
 For example to get 5 workers change the setting `--workers=5` in your `supervisor.conf` file and then reload the supervisor with the following command to activate the change (Ubuntu):
 
-```bash
+```shell
 systemctl restart supervisor
 ```

docs/maintenance/tuning/index.md

@@ -2,13 +2,12 @@
 
 The official installation guide will install a stable version of Alliance Auth that will work fine for most cases. However, there are a lot of levels that can be used to optimize a system. For example some installations may we short on RAM and want to reduce the total memory footprint, even though that may reduce system performance. Others are fine with further increasing the memory footprint to get better system performance.
 
-```eval_rst
+```{eval-rst}
 .. warning::
     Tuning usually has benefits and costs and should only be performed by experienced Linux administrators who understand the impact of tuning decisions on to their system.
 ```
 
-```eval_rst
+```{toctree}
-.. toctree::
 :maxdepth: 1
 
 gunicorn