[docs] Restructured docs

README.rst

@@ -10,15 +10,23 @@ ansible-openwisp2
     :alt: Galaxy
 
 .. image:: https://img.shields.io/gitter/room/nwjs/nw.js.svg
-   :target: https://gitter.im/openwisp/general
-   :alt: Chat
+    :target: https://gitter.im/openwisp/general
+    :alt: Chat
 
 Ansible role that installs the OpenWISP Server Application.
 
 Tested on **Debian (Bullseye)**, **Ubuntu (20/22 LTS)**.
 
 **Recommended ansible version**: 2.12.
 
+Documentation
+-------------
+
+- `Developer documentation
+  <https://openwisp.io/docs/__new__/dev/ansible-openwisp2/developer/>`_
+- `User documentation
+  <https://openwisp.io/docs/__new__/dev/ansible-openwisp2/>`_
+
 Support
 -------
 

docs/developer/installation.rst

@@ -1,10 +1,10 @@
-Install ansible-openwisp2 for development
-=========================================
+Developer Installation instructions
+===================================
 
-.. note::
+.. include:: ../partials/developer-docs.rst
 
-    If you need to modify the logic of this ansible role and you need to
-    test your changes here we explain how to do it.
+Installing for Development
+--------------------------
 
 First of all, create the directory where you want to place the
 repositories of the ansible roles and create directory roles.
@@ -33,15 +33,14 @@ Now, go to the parent directory & create hosts file and playbook.yml:
 From here on you can follow the instructions available at the following
 sections:
 
-- `Create inventory file <#create-inventory-file>`__
-- `Create playbook file <#create-playbook-file>`__
-- `Run the playbook <#run-the-playbook>`__
-
-**Note:** Please remember to `install ansible <#install-ansible>`__.
+- :ref:`ansible_install`
+- :ref:`ansible_create_inventory_file`
+- :ref:`ansible_create_playbook_file`
+- :ref:`ansible_run_playbook`
 
 All done!
 
-How to run tests
+How to Run Tests
 ----------------
 
 If you want to contribute to ``ansible-openwisp2`` you should run tests in
@@ -54,7 +53,7 @@ To do that, proceed with the following steps:
 
 Clone repository by:
 
-.. code-block::
+.. code-block:: shell
 
     git clone https://github.com/<your_fork>/ansible-openwisp2.git openwisp.openwisp2
     cd openwisp.openwisp2
@@ -64,27 +63,27 @@ Clone repository by:
 If you haven't installed docker yet, you need to install it (example for
 linux debian/ubuntu systems):
 
-.. code-block::
+.. code-block:: shell
 
-    sudo apt-get install docker.io
+    sudo apt install docker.io
 
-**Step 3**: Install molecule and dependences
+**Step 3**: Install molecule and dependencies
 
-.. code-block::
+.. code-block:: shell
 
     pip install molecule[docker] molecule-plugins yamllint ansible-lint docker
 
 **Step 4**: Download docker images
 
-.. code-block::
+.. code-block:: shell
 
     docker pull geerlingguy/docker-ubuntu2204-ansible:latest
     docker pull geerlingguy/docker-ubuntu2004-ansible:latest
     docker pull geerlingguy/docker-debian11-ansible:latest
 
 **Step 5**: Run molecule test
 
-.. code-block::
+.. code-block:: shell
 
     molecule test -s local
 

docs/index.rst

@@ -1,30 +1,29 @@
-Ansible OpenWISP2
-=================
+Ansible OpenWISP
+================
 
 Ansible role that installs the OpenWISP Server Application.
 
-**Recommended ansible version**: 2.12.
-Tested on **Debian (Bullseye)**, **Ubuntu (20/22 LTS)**.
+**Recommended ansible version**: ``2.12``
 
 .. toctree::
     :caption: User Docs
     :maxdepth: 1
 
-    ./system-requirements.rst
-    ./deploying-openwisp.rst
-    ./automatic-ssl-support.rst
-    ./enabling-monitoring.rst
-    ./enabling-firmware-upgrader.rst
-    ./enabling-network-topology.rst
-    ./enabling-radius.rst
-    ./deploying-custom-static-content.rst
-    ./configuring-cors-headers.rst
-    ./installing-on-vm.rst
-    ./troubleshooting.rst
-    ./role-variables.rst
+    ./user/system-requirements.rst
+    ./user/quickstart.rst
+    ./user/certbot-ssl.rst
+    ./user/enabling-monitoring.rst
+    ./user/enabling-firmware-upgrader.rst
+    ./user/enabling-network-topology.rst
+    ./user/enabling-radius.rst
+    ./user/deploying-custom-static-content.rst
+    ./user/configuring-cors-headers.rst
+    ./user/installing-on-vm.rst
+    ./user/troubleshooting.rst
+    ./user/role-variables.rst
 
 .. toctree::
     :caption: Developer Docs
-    :maxdepth: 2
+    :maxdepth: 1
 
-    Developer Docs Index <developer/index.rst>
+    ./developer/installation.rst

docs/partials/developer-docs.rst

@@ -0,0 +1,12 @@
+.. note::
+
+    This documentation page is aimed at developers who want to customize,
+    change or extend the code of Ansible OpenWISP2 in order to modify its
+    behavior (eg: for personal or commercial purposes or to fix a bug,
+    implement a new feature or contribute to the project in general).
+
+    If you aren't a developer and you are looking for information on how
+    to use OpenWISP, please refer to:
+
+    - :doc:`General OpenWISP Quickstart </user/quickstart>`
+    - :doc:`Ansible OpenWISP2 User Docs </ansible-openwisp2/index>`

docs/user/automatic-ssl-support.rst → docs/user/certbot-ssl.rst

@@ -1,12 +1,12 @@
-Automatic SSL certificate
-=========================
+Using Let's Encrypt SSL Certificate
+===================================
 
 This section explains how to **automatically install and renew a valid SSL
-certificate** signed by `letsencrypt <https://letsencrypt.org/>`__.
+certificate** signed by `Let's Encrypt <https://letsencrypt.org/>`__.
 
 The first thing you have to do is to setup a valid domain for your
-openwisp2 instance, this means your inventory file (hosts) should look
-like the following:
+OpenWISP instance, this means your inventory file (hosts) should look like
+the following:
 
 .. code-block:: text
 

docs/user/configuring-cors-headers.rst

@@ -9,11 +9,11 @@ allows users to configure the CORS headers with the help of
 <https://github.com/adamchainz/django-cors-headers>`__ package. Here's a
 short summary of how to do this:
 
-**Step 1**: `Install ansible <#install-ansible>`__
+**Step 1**: :ref:`Install ansible <ansible_install>`
 
-**Step 2**: `Install this role <#install-this-role>`__
+**Step 2**: :ref:`Install this role <ansible_install_role>`
 
-**Step 3**: `Create inventory file <#create-inventory-file>`__
+**Step 3**: :ref:`Create inventory file <ansible_create_inventory_file>`
 
 **Step 4**: Create a playbook file with following contents:
 
@@ -33,16 +33,16 @@ short summary of how to do this:
 
 **Note:** to learn about the supported fields of the
 ``openwisp2_django_cors`` variable, look for the word
-“openwisp2_django_cors” in the `Role variables <#role-variables>`__
-section of this document.
+“openwisp2_django_cors” in the :doc:`role-variables` section of this
+document.
 
-**Step 5**: `Run the playbook <#run-the-playbook>`__
+**Step 5**: :ref:`Run the playbook <ansible_run_playbook>`
 
-When the playbook is done running, if you got no errors you can login at:
+When the playbook is done running, if you got no errors you can login at
+https://openwisp2.mydomain.com/admin, with the following credentials:
 
-.. code-block::
+.. code-block:: text
 
-    https://openwisp2.mydomain.com/admin
     username: admin
     password: admin
 

docs/user/deploying-custom-static-content.rst

@@ -1,16 +1,14 @@
-Deploying custom static content
+Deploying Custom Static Content
 ===============================
 
 For deploying custom static content (HTML files, etc.) add all the static
 content in ``files/ow2_static`` directory. The files inside
 ``files/ow2_static`` will be uploaded to a directory named
 ``static_custom`` in ``openwisp2_path``.
 
-This is helpful for `customizing OpenWISP's theme
-<https://github.com/openwisp/openwisp-utils#openwisp_admin_theme_links>`__.
+This is helpful for :ref:`customizing OpenWISP's theme
+<openwisp_admin_theme_links>`.
 
 E.g., if you added a custom CSS file in
 ``files/ow2_static/css/custom.css``, the file location to use in
-`OPENWISP_ADMIN_THEME_LINKS
-<https://github.com/openwisp/openwisp-utils#openwisp_admin_theme_links>`__
-setting will be ``css/custom.css``.
+:ref:`openwisp_admin_theme_links` setting will be ``css/custom.css``.

docs/user/enabling-firmware-upgrader.rst

@@ -1,19 +1,19 @@
-Enabling the Firmware Upgrader modules
-======================================
+Enabling the Firmware Upgrader Module
+=====================================
 
 **Note**: It is encouraged that you read the :doc:`quick-start guide of
-openwisp-firmware-upgrader </firmware-upgrader/user/index>` before going
-ahead.
+openwisp-firmware-upgrader </firmware-upgrader/user/quickstart>` before
+going ahead.
 
-To enable the :doc:`Firmware Upgrader </firmware-upgrader/user/index>`
-module you need to set ``openwisp2_firmware_upgrader`` to ``true`` in your
+To enable the :doc:`Firmware Upgrader </firmware-upgrader/index>` module
+you need to set ``openwisp2_firmware_upgrader`` to ``true`` in your
 ``playbook.yml`` file. Here's a short summary of how to do this:
 
-**Step 1**: :ref:`Install ansible <onstall_ansible>`
+**Step 1**: :ref:`Install ansible <ansible_install>`
 
-**Step 2**: `Install this role <#install-this-role>`__
+**Step 2**: :ref:`Install this role <ansible_install_role>`
 
-**Step 3**: `Create inventory file <#create-inventory-file>`__
+**Step 3**: :ref:`Create inventory file <ansible_create_inventory_file>`
 
 **Step 4**: Create a playbook file with following contents:
 
@@ -26,18 +26,18 @@ module you need to set ``openwisp2_firmware_upgrader`` to ``true`` in your
       vars:
         openwisp2_firmware_upgrader: true
 
-**Step 5**: `Run the playbook <#run-the-playbook>`__
+**Step 5**: :ref:`Run the playbook <ansible_run_playbook>`
 
 When the playbook is done running, if you got no errors you can login at
-``https://openwisp2.mydomain.com/admin`` with the following credentials:
+https://openwisp2.mydomain.com/admin with the following credentials:
 
 .. code-block:: text
 
     username: admin
     password: admin
 
-**Note**: You can configure :doc:`openwisp-firmware-upgrader specific
-settings <firmware-upgrader/user/settings>` using the
+You can configure :doc:`openwisp-firmware-upgrader specific settings
+<firmware-upgrader/user/settings>` using the
 ``openwisp2_extra_django_settings`` or
 ``openwisp2_extra_django_settings_instructions``.
 
@@ -59,3 +59,6 @@ E.g:
                     'boards': ('MyCustomImage',)
                 }),
             )
+
+Refer the :doc:`role-variables` section of the documentation for a
+complete list of available role variables.

docs/user/enabling-monitoring.rst

@@ -1,6 +1,5 @@
-Enabling the Monitoring module
+Enabling the Monitoring Module
 ==============================
 
-The `Monitoring module <https://openwisp.io/docs/user/monitoring.html>`__
-is enabled by default, it can be disabled by setting
-``openwisp2_monitoring`` to ``false``.
+The :doc:`Monitoring module </monitoring/index>` is enabled by default, it
+can be disabled by setting ``openwisp2_monitoring`` to ``false``.

docs/user/enabling-network-topology.rst

@@ -1,16 +1,15 @@
-Enabling the Network Topology module
+Enabling the Network Topology Module
 ====================================
 
-To enable the `Network Topology module
-<https://openwisp.io/docs/user/network-topology.html>`__ you need to set
-``openwisp2_network_topology`` to ``true`` in your ``playbook.yml`` file.
-Here's a short summary of how to do this:
+To enable the :doc:`Network Topology module <network-topology/index>` you
+need to set ``openwisp2_network_topology`` to ``true`` in your
+``playbook.yml`` file. Here's a short summary of how to do this:
 
-**Step 1**: `Install ansible <#install-ansible>`__
+**Step 1**: :ref:`Install ansible <ansible_install>`
 
-**Step 2**: `Install this role <#install-this-role>`__
+**Step 2**: :ref:`Install this role <ansible_install_role>`
 
-**Step 3**: `Create inventory file <#create-inventory-file>`__
+**Step 3**: :ref:`Create inventory file <ansible_create_inventory_file>`
 
 **Step 4**: Create a playbook file with following contents:
 
@@ -23,12 +22,12 @@ Here's a short summary of how to do this:
       vars:
         openwisp2_network_topology: true
 
-**Step 5**: `Run the playbook <#run-the-playbook>`__
+**Step 5**: :ref:`Run the playbook <ansible_run_playbook>`
 
-When the playbook is done running, if you got no errors you can login at:
+When the playbook is done running, if you got no errors you can login at
+https://openwisp2.mydomain.com/admin with the following credentials:
 
-.. code-block::
+.. code-block:: text
 
-    https://openwisp2.mydomain.com/admin
     username: admin
     password: admin