docs(ci): use 'doc8' to check ReStructuredText files

Add it to the CI and resolve issues found.

Author: JohnVillalovos

.github/workflows/lint-and-analyse-php.yml

@@ -31,6 +31,8 @@ jobs:
         run: tox -e cz
       - name: Run config-check
         run: tox -e config-check
+      - name: Run doc8
+        run: tox -e doc8
       - name: Ensure no merge-commits in the Pull Request (PR)
         if: github.event_name == 'pull_request'
         run: |

docs/source/ADVANCED-CONFIGURATION.rst

@@ -1,14 +1,18 @@
 Advanced Configuration
 ======================
 
-This guide covers all advanced configuration options available in LibreBooking. For basic setup, see :doc:`BASIC-CONFIGURATION` first.
+This guide covers all advanced configuration options available in LibreBooking.
+For basic setup, see :doc:`BASIC-CONFIGURATION` first.
 
-All settings are configured in the ``/config/config.php`` file. The configuration uses a mix of flat dot notation and nested arrays.
+All settings are configured in the ``/config/config.php`` file. The
+configuration uses a mix of flat dot notation and nested arrays.
 
 Environment Variable Override
 -----------------------------
 
-LibreBooking supports overriding any configuration setting using environment variables. This provides flexibility for deployment scenarios and keeps sensitive data separate from configuration files.
+LibreBooking supports overriding any configuration setting using environment
+variables. This provides flexibility for deployment scenarios and keeps
+sensitive data separate from configuration files.
 
 **Naming Convention**
   Environment variables follow the pattern: ``LB_`` + config key with special characters converted:
@@ -51,7 +55,8 @@ LibreBooking supports overriding any configuration setting using environment var
            - LB_ADMIN_EMAIL=admin@company.com
 
 **Complete Example**
-  See ``develop/app/.env.example`` for a comprehensive list of all available environment variables with their default values and descriptions.
+  See ``develop/app/.env.example`` for a comprehensive list of all available
+  environment variables with their default values and descriptions.
 
 Application Advanced Settings
 -----------------------------
@@ -262,7 +267,10 @@ Schedule Display Settings
   Show resources that users cannot book (grayed out).
 
 **schedule.reservation.label**
-  Template for reservation labels. Available tokens: {name}, {title}, {description}, {email}, {phone}, {organization}, {position}, {startdate}, {enddate}, {resourcename}, {participants}, {invitees}, {reservationAttributes}, and custom attributes like {att1}.
+  Template for reservation labels. Available tokens: {name}, {title},
+  {description}, {email}, {phone}, {organization}, {position}, {startdate},
+  {enddate}, {resourcename}, {participants}, {invitees},
+  {reservationAttributes}, and custom attributes like {att1}.
 
 **schedule.use.per.user.colors**
   Use different colors for each user's reservations.
@@ -354,7 +362,8 @@ Reservation Label Templates
        'reservation.popup' => '',
    ],
 
-These templates control how reservations appear in different contexts using the same tokens as schedule.reservation.label.
+These templates control how reservations appear in different contexts using the
+same tokens as schedule.reservation.label.
 
 Reports Settings
 ----------------
@@ -728,7 +737,8 @@ Plugin System
        'styling' => '',
    ],
 
-Available authentication plugins: ActiveDirectory, Apache, CAS, Drupal, Krb5, Ldap, Mellon, Moodle, MoodleAdv, Saml, Shibboleth, WordPress.
+Available authentication plugins: ActiveDirectory, Apache, CAS, Drupal, Krb5,
+Ldap, Mellon, Moodle, MoodleAdv, Saml, Shibboleth, WordPress.
 
 For authentication plugin configuration, see:
 

docs/source/ActiveDirectory-Authentication.rst

@@ -1,7 +1,8 @@
 Active Directory Authentication
 ================================
 
-The Active Directory authentication plugin provides enhanced support for Microsoft Active Directory with features like Single Sign-On (SSO).
+The Active Directory authentication plugin provides enhanced support for
+Microsoft Active Directory with features like Single Sign-On (SSO).
 
 Enable the Plugin
 -----------------
@@ -14,7 +15,8 @@ Edit ``/config/config.php`` and set:
        'authentication' => 'ActiveDirectory',
    ],
 
-Alternatively, enable the plugin through the web admin interface at **Application Configuration** (``/Web/admin/manage_configuration.php``).
+Alternatively, enable the plugin through the web admin interface at
+**Application Configuration** (``/Web/admin/manage_configuration.php``).
 
 Configuration
 -------------
@@ -25,19 +27,27 @@ If not existing already, copy the template and edit with your Active Directory s
 
    cp /plugins/Authentication/ActiveDirectory/ActiveDirectory.config.dist.php /config/ActiveDirectory.config.php
 
-The configuration file at ``/config/ActiveDirectory.config.php`` contains all available options with detailed comments. You can also view and modify these settings through the web admin interface at **Application Management > Configuration**. Key settings include:
+The configuration file at ``/config/ActiveDirectory.config.php`` contains all
+available options with detailed comments. You can also view and modify these
+settings through the web admin interface at **Application Management >
+Configuration**. Key settings include:
 
 - **domain.controllers**: Comma-separated list of domain controller hostnames
 - **username/password**: Service account credentials for AD searches
 - **basedn**: Base DN in DC= format (e.g., ``DC=example,DC=com``)
 - **account.suffix**: Domain suffix for user logins (e.g., ``@example.com``)
-- **attribute.mapping**: Maps AD attributes to LibreBooking fields (note: AD uses ``givenName``, ``telephoneNumber``, etc.)
+- **attribute.mapping**: Maps AD attributes to LibreBooking fields (note: AD
+  uses ``givenName``, ``telephoneNumber``, etc.)
 - **sync.groups**: Enable group membership synchronization
 - **use.sso**: Enable Windows Single Sign-On
 - **database.auth.when.ldap.user.not.found**: Fallback to database authentication
 
-Alternatively, configure the plugin through the web admin interface at **Application Configuration** (``/Web/admin/manage_configuration.php``) and select **Authentification-ActiveDirectory**.
-Refer to ``/plugins/Authentication/ActiveDirectory/ActiveDirectory.config.dist.php`` for complete documentation of all options.
+Alternatively, configure the plugin through the web admin interface at
+**Application Configuration** (``/Web/admin/manage_configuration.php``) and
+select **Authentification-ActiveDirectory**.
+Refer to
+``/plugins/Authentication/ActiveDirectory/ActiveDirectory.config.dist.php`` for
+complete documentation of all options.
 
 User Login
 ----------
@@ -52,28 +62,32 @@ This simplifies the login experience while maintaining proper AD authentication.
 Single Sign-On (SSO)
 --------------------
 
-When ``use.sso`` is enabled, users are automatically authenticated using their Windows login credentials.
+When ``use.sso`` is enabled, users are automatically authenticated using their
+Windows login credentials.
 
 Requirements:
 
 - Web server configured for Windows authentication:
-  
+
   - IIS with Windows Authentication enabled
   - Apache with mod_auth_sspi or mod_auth_kerb
 
 - Browsers configured to send Windows credentials automatically
 - Users accessing from domain-joined computers
 - The ``$_SERVER['REMOTE_USER']`` variable populated by the web server
 
-With SSO enabled, users won't see a login page - they're automatically logged in using their Windows credentials.
+With SSO enabled, users won't see a login page - they're automatically logged
+in using their Windows credentials.
 
 Troubleshooting
 ---------------
 
 Enable Debug Logging
 ~~~~~~~~~~~~~~~~~~~~
 
-Set ``debug.enabled`` to ``true`` in the Ldap plugin configuration (Active Directory uses the same logging) to see detailed operations in LibreBooking logs.
+Set ``debug.enabled`` to ``true`` in the Ldap plugin configuration (Active
+Directory uses the same logging) to see detailed operations in LibreBooking
+logs.
 
 Migration from Database Auth
 -----------------------------
@@ -85,4 +99,5 @@ To migrate existing users:
 3. Users automatically switch to AD auth on next login
 4. Existing reservations and data are preserved
 
-Users are matched by username - if a LibreBooking account exists with the same username, it will be updated with AD information.
+Users are matched by username - if a LibreBooking account exists with the same
+username, it will be updated with AD information.

docs/source/BASIC-CONFIGURATION.rst

@@ -1,9 +1,14 @@
 Basic Configuration
 ===================
 
-This guide covers the essential configuration settings needed to get LibreBooking up and running. All settings are configured in the ``/config/config.php`` file, which should be created by copying ``/config/config.dist.php``.
+This guide covers the essential configuration settings needed to get
+LibreBooking up and running. All settings are configured in the
+``/config/config.php`` file, which should be created by copying
+``/config/config.dist.php``.
 
-The configuration file uses a PHP array format that returns a settings array. Some settings use nested arrays (like database settings), while others use flat dot notation.
+The configuration file uses a PHP array format that returns a settings array.
+Some settings use nested arrays (like database settings), while others use flat
+dot notation.
 
 Getting Started
 ---------------
@@ -19,10 +24,13 @@ Then edit the file with your preferred settings.
 Environment Variable Override
 -----------------------------
 
-LibreBooking supports overriding configuration settings using environment variables. This is especially useful for Docker deployments or when you want to keep sensitive information separate from configuration files.
+LibreBooking supports overriding configuration settings using environment
+variables. This is especially useful for Docker deployments or when you want to
+keep sensitive information separate from configuration files.
 
 **Pattern**
-  Environment variables follow the pattern ``LB_`` + the config key with dots and dashes converted to underscores and converted to uppercase.
+  Environment variables follow the pattern ``LB_`` + the config key with dots
+  and dashes converted to underscores and converted to uppercase.
 
 **Examples**
 
@@ -32,10 +40,13 @@ LibreBooking supports overriding configuration settings using environment variab
 - ``default.timezone`` → ``LB_DEFAULT_TIMEZONE``
 
 **Using .env Files**
-  LibreBooking automatically loads ``.env`` files if present in the root directory. See ``develop/app/.env.example`` for a complete list of available environment variables.
+  LibreBooking automatically loads ``.env`` files if present in the root
+  directory. See ``develop/app/.env.example`` for a complete list of available
+  environment variables.
 
 **Priority**
-  Environment variables take precedence over configuration file settings. The order of precedence is:
+  Environment variables take precedence over configuration file settings. The
+  order of precedence is:
 
   1. Environment variables (highest priority)
   2. Configuration file settings
@@ -49,47 +60,47 @@ Application Identity
 
 **app.title**
   The title of the application displayed in the header and browser tab.
-  
+
   .. code-block:: php
-  
+
      'app.title' => 'LibreBooking',
 
 **admin.email**
   Administrator email address.
-  
+
   .. code-block:: php
-  
+
      'admin.email' => 'admin@example.com',
 
 **company.name**
   Company name to show in the page header.
-  
+
   .. code-block:: php
-  
+
      'company.name' => '',
 
 **company.url**
   URL to the company's website.
-  
+
   .. code-block:: php
-  
+
      'company.url' => '',
 
 Time and Language
 ~~~~~~~~~~~~~~~~~
 
 **default.timezone**
   Look up here http://php.net/manual/en/timezones.php.
-  
+
   .. code-block:: php
-  
+
      'default.timezone' => 'Europe/London',
 
 **default.language**
   Default language for the application.
-  
+
   .. code-block:: php
-  
+
      'default.language' => 'en_us',
 
 Database Configuration
@@ -273,7 +284,8 @@ Frontend Settings
   Public URL to the Web directory of this instance.
 
 **css.theme**
-  Theme to use for the application. Options: default, dimgray, dark_red, dark_green, french_blue, cake_blue, orange.
+  Theme to use for the application. Options: default, dimgray, dark_red,
+  dark_green, french_blue, cake_blue, orange.
 
 **cache.templates**
   Enable or disable template caching.
@@ -286,9 +298,9 @@ Installation
 
 **install.password**
   Password required for installation or upgrades.
-  
+
   .. code-block:: php
-  
+
      'install.password' => '',
 
 Basic Privacy Settings
@@ -325,7 +337,8 @@ After configuring these basic settings:
 Docker Installation
 ===================
 
-LibreBooking can be easily deployed using Docker containers. This is the recommended method for quick setup and testing.
+LibreBooking can be easily deployed using Docker containers. This is the
+recommended method for quick setup and testing.
 
 Prerequisites
 -------------
@@ -353,7 +366,7 @@ Quick Start with Docker Compose
             - PGID=1000
             - TZ=America/New_York
             - MYSQL_ROOT_PASSWORD=your_secure_root_password
-        
+
         app:
           image: librebooking/librebooking:develop
           restart: always

docs/source/CONFIGURATION.rst

@@ -33,7 +33,8 @@ This covers:
 Configuration File Format
 -------------------------
 
-LibreBooking uses a PHP array-based configuration format. The file returns a settings array with both flat dot notation and nested arrays:
+LibreBooking uses a PHP array-based configuration format. The file returns a
+settings array with both flat dot notation and nested arrays:
 
 .. code-block:: php
 
@@ -43,7 +44,7 @@ LibreBooking uses a PHP array-based configuration format. The file returns a set
            // Flat keys
            'app.title' => 'LibreBooking',
            'admin.email' => 'admin@example.com',
-           
+
            // Nested arrays
            'database' => [
                'type' => 'mysql',
@@ -52,7 +53,7 @@ LibreBooking uses a PHP array-based configuration format. The file returns a set
                'user' => 'lb_user',
                'password' => 'password',
            ],
-           
+
            'email' => [
                'enabled' => true,
                'default.from.address' => 'noreply@example.com',
@@ -71,4 +72,6 @@ Quick Start
 Migration from Old Format
 -------------------------
 
-If upgrading from an older version that used ``$conf['settings'][...]`` format, you'll need to convert your configuration to the new array return format. The new format is more modern and provides better IDE support and validation.
+If upgrading from an older version that used ``$conf['settings'][...]`` format,
+you'll need to convert your configuration to the new array return format. The
+new format is more modern and provides better IDE support and validation.

docs/source/HISTORY.rst

@@ -8,7 +8,7 @@ Since forking from Booked Scheduler, LibreBooking has evolved significantly:
 
 - Modernized PHP codebase with improved compatibility
 - Enhanced configuration system with comprehensive documentation
-- Improved Docker deployment support  
+- Improved Docker deployment support
 - Updated dependencies and security fixes
 - Enhanced user interface and user experience
 - Expanded API capabilities