Use autosection and get rid of conflicting headers

Author: marc1706

development/conf.py

@@ -35,7 +35,8 @@
     'sensio.sphinx.bestpractice',
     'sphinxcontrib.phpdomain',
     'sphinx_multiversion',
-    'sphinx_rtd_theme'
+    'sphinx_rtd_theme',
+    'sphinx.ext.autosectionlabel'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -101,6 +102,8 @@
 # If true, keep warnings as "system message" paragraphs in the built documents.
 #keep_warnings = False
 
+autosectionlabel_prefix_document = True
+
 # Options for sphinx_multiversion
 smv_tag_whitelist = 'None'
 smv_branch_whitelist = r'^(3.2.x|3.3.x|master)$'

development/db/dbal.rst

@@ -49,8 +49,7 @@ Example using :class:`config.php`:
     // We do not need this any longer, unset for safety purposes
     unset($dbpasswd);
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
 
 .. csv-table::
    :header: Parameter, Usage
@@ -115,8 +114,8 @@ Example:
     // Now run the query...
     $result = $db->sql_query($sql);
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
    :header: Parameter, Usage
    :delim: #
@@ -155,8 +154,8 @@ Example:
     $sql = 'INSERT INTO ' . USERS_TABLE . ' ' . $db->sql_build_array('INSERT', $data);
     $db->sql_query($sql);
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
    :header: Parameter, Usage
    :delim: #
@@ -179,8 +178,8 @@ Example:
     	WHERE ' . $db->sql_in_set('user_id', $sql_in);
 
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
    :header: Parameter, Usage
    :delim: |
@@ -204,8 +203,8 @@ Example:
     	WHERE post_id = ' . (int) $integer . "
     		AND post_text = '" . $db->sql_escape($string) . "'";
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
    :header: Parameter, Usage
    :delim: |
@@ -220,8 +219,8 @@ Defined in the base driver (``_sql_like_expression`` is defined in the specific
 
 The ``sql_not_like_expression`` is identical to ``sql_like_expression`` apart from that it builds a NOT LIKE statement.
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
    :header: Parameter, Usage
    :delim: |
@@ -266,8 +265,8 @@ Example:
     	WHERE ' . $db->sql_lower_text('log_data') . ' ' . $like;
     $result = $db->sql_query_limit($sql, 10);
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
    :header: Parameter, Usage
    :delim: |
@@ -295,8 +294,8 @@ Example:
     $result = $db->sql_query($sql);
 
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
    :header: Parameter, Usage
    :delim: |
@@ -320,8 +319,8 @@ Example:
     $result = $db->sql_query_limit($sql, $config['topics_per_page'], $start);
 
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
    :header: Parameter, Usage
    :delim: |
@@ -356,8 +355,8 @@ Example:
     $db->sql_multi_insert(USER_GROUP_TABLE, $sql_ary);
 
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
    :header: Parameter, Usage
    :delim: |
@@ -424,8 +423,8 @@ Example:
     $total_posts = (int) $db->sql_fetchfield('num_posts');
 
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
    :header: Parameter, Usage
    :delim: #
@@ -438,9 +437,8 @@ sql_fetchrowset
 ---------------
 Returns an array with the result of using the ``sql_fetchrow`` method on every row. Defined in the base driver.
 
+.. rubric:: Parameters
 
-Parameters
-^^^^^^^^^^
 .. csv-table::
    :header: Parameter, Usage
    :delim: #
@@ -476,9 +474,8 @@ Example with a while-loop:
     	$config[$row['config_name']] = $row['config_value'];
     }
 
+.. rubric:: Parameters
 
-Parameters
-^^^^^^^^^^
 .. csv-table::
    :header: Parameter, Usage
    :delim: #
@@ -489,9 +486,8 @@ sql_rowseek
 -----------
 Seeks to given row number. The row number is zero-based. Defined in the specific drivers.
 
+.. rubric:: Parameters
 
-Parameters
-^^^^^^^^^^
 .. csv-table::
    :header: Parameter, Usage
    :delim: #
@@ -519,9 +515,8 @@ Example:
     // We don't need to do anything with our query anymore, so lets set it free
     $db->sql_freeresult($result);
 
+.. rubric:: Parameters
 
-Parameters
-^^^^^^^^^^
 .. csv-table::
    :header: Parameter, Usage
    :delim: #

development/development/css/css_specificity.rst

@@ -169,10 +169,9 @@ This goes some way to providing our CSS with scope and encapsulation, but does s
 
 Now we have better scoped CSS with minimal specificity—the best of both worlds.
 
-Further Reading
-^^^^^^^^^^^^^^^
+.. seealso::
 
--  `‘Scope’ in CSS`_
+    -  `‘Scope’ in CSS`_
 
 ``!important``
 ~~~~~~~~~~~~~~
@@ -272,12 +271,11 @@ Here we are selecting based on an attribute rather than an ID, and attribute sel
 
 Do keep in mind that these are hacks, and should not be used unless you have no better alternative.
 
-Further Reading
-^^^^^^^^^^^^^^^
+.. seealso::
 
--  `Hacks for dealing with specificity`_
+    -  `Hacks for dealing with specificity`_
 
-.. _jsfiddle.net/0yb7rque: https://jsfiddle.net/csswizardry/0yb7rque/
-.. _known bug: https://web.archive.org/web/20200512073642/https://twitter.com/codepo8/status/505004085398224896
-.. _‘Scope’ in CSS: https://csswizardry.com/2013/05/scope-in-css/
-.. _Hacks for dealing with specificity: https://csswizardry.com/2014/07/hacks-for-dealing-with-specificity/
+    .. _jsfiddle.net/0yb7rque: https://jsfiddle.net/csswizardry/0yb7rque/
+    .. _known bug: https://web.archive.org/web/20200512073642/https://twitter.com/codepo8/status/505004085398224896
+    .. _‘Scope’ in CSS: https://csswizardry.com/2013/05/scope-in-css/
+    .. _Hacks for dealing with specificity: https://csswizardry.com/2014/07/hacks-for-dealing-with-specificity/

development/development/git.rst

@@ -138,8 +138,10 @@ Review `Forking and Cloning`_.
 
 Configuration
 -------------
-Git
-^^^
+
+.. rubric:: Git
+    :heading-level: 4
+
 Add your Username to Git on your system:
 
 ::
@@ -162,8 +164,9 @@ Add the upstream remote (you can change 'upstream' to whatever you like):
     The *upstream* remote url **is** the phpBB GitHub repo. Your cloned
     fork of the phpBB GitHub repo will, by default, use the *origin* remote url.
 
-Composer
-^^^^^^^^
+.. rubric:: Composer
+    :heading-level: 4
+
 To be able to run an installation from the repo (and not from a pre-built package) you
 need to run the following shell commands to install phpBB's dependencies.
 
@@ -179,8 +182,9 @@ Ignore any *abandoned package* warnings.
     `Introduction - Composer <https://getcomposer.org/doc/00-intro.md>`_ for
     further information.
 
-Hooks
-^^^^^
+.. rubric:: Hooks
+    :heading-level: 4
+
 The phpBB repository contains some client-side hooks that can aid development. They are
 located in the ``git-tools/hooks`` directory. These hooks do things like preparing and
 validating commit messages, checking for PHP syntax errors. There is a script to set

development/extensions/tutorial_authentication.rst

@@ -24,8 +24,8 @@ Creating an Authentication Provider
 Authentication providers in phpBB require a minimum of two files: a PHP class
 and a YAML service file.
 
-The class file
-^^^^^^^^^^^^^^
+.. rubric:: The class file
+
 The provider class must implement the ``\phpbb\auth\provider\provider_interface`` in order to
 ensure proper functionality. However, it is recommended to extend
 ``\phpbb\auth\provider\base`` so as to not implement unneeded methods and to ensure
@@ -104,8 +104,8 @@ authentication provider class is show below:
         }
     }
 
-The service file
-^^^^^^^^^^^^^^^^
+.. rubric:: service file
+
 For proper :ref:`dependency injection <dependency-injection>`
 the provider must be added to ``services.yml``. The name of the service 
 must be in the form of ``auth.provider.<service name>`` in order for phpBB to register it.
@@ -123,8 +123,8 @@ for the class to be made available in phpBB.
             tags:
                 - { name: auth.provider }
 
-The template file
-^^^^^^^^^^^^^^^^^
+.. rubric:: template file
+
 Following the above steps renders the authentication provider visible in the ACP.
 However, to allow an admin to configure your plugin the available fields need to
 be created in order to reach the configuration from the php-auth-provider plugin.
@@ -168,8 +168,8 @@ The example files below show the minimum needed to enable an OAuth service in
 phpBB. They are copies of the bitly service implementation from phpBB's
 develop branch.
 
-The Class file
-^^^^^^^^^^^^^^
+.. rubric:: The Class file
+
 .. code-block:: php
 
     <?php
@@ -267,8 +267,7 @@ The Class file
         }
     }
 
-The Service File
-^^^^^^^^^^^^^^^^
+.. rubric:: service file
 
 In the service file, the name of the service must be in the form of
 ``auth.provider.oauth.service.<service name>`` in order for phpBB to

development/extensions/tutorial_notifications.rst

@@ -1033,8 +1033,7 @@ This function is very simple to use, and requires only a few basic parameters:
 delete_notifications
 --------------------
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
 
 .. csv-table::
    :header: Parameter, Description
@@ -1080,8 +1079,7 @@ The following is a quick summary of the three methods available for marking noti
 mark_notifications
 ------------------
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
 
 .. csv-table::
    :header: Parameter, Description
@@ -1096,8 +1094,7 @@ Parameters
 mark_notifications_by_parent
 ----------------------------
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
 
 .. csv-table::
    :header: Parameter, Description
@@ -1117,8 +1114,7 @@ as most of the notification handling is done through the distinct item and/or pa
 However, there can be times where it is more convenient or accurate to work directly with the notification's unique id.
 For example, when the notifications are listed in the :abbr:`UCP (User Control Panel)` and a user can select specific notifications to be marked as read.
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
 
 .. csv-table::
    :header: Parameter, Description

development/extensions/tutorial_templates.rst

@@ -129,10 +129,10 @@ To make comments inside the template you can use ``{# #}``:
 
     {# Your comments can go here. #}
 
-Variables
----------
+Template variables
+------------------
 
-Variables in phpBB take the form of ``{{ X_YYYYY }}``, where the data is assigned from the source. However, most
+Template variables in phpBB take the form of ``{{ X_YYYYY }}``, where the data is assigned from the source. However, most
 language strings are not assigned from the source. When a language variable is found, denoted as ``{{ lang('YYYYYY') }}``,
 phpBB first checks if an assigned variable with that name exists. If it does, it uses that. If not, it checks if an
 existing string defined in the language file exists.
@@ -141,8 +141,8 @@ By using the language variable format, phpBB allows for more flexibility in the
 This allows for easy modifications of language strings in the language files without having to modify the source code
 directly.
 
-Blocks
-------
+Template blocks
+---------------
 
 The basic block level loop takes the form: