Merge pull request #304 from phpbb/update/phpbb_specifiers

Update phpBB specifiers and update templating coding guidelines for phpBB 4.0

Author: marc1706

development/Makefile

@@ -9,7 +9,7 @@ BUILDDIR      = _build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from https://sphinx-doc.org/)
 endif
 
 # Internal variables.

development/cli/getting_started.rst

@@ -4,7 +4,7 @@ Getting started
 
 The command line interface (CLI) is a useful utility for phpBB administrators who have access to a shell (or SSH) on the server they run phpBB on, as well as for extension developers. It provides CLI commands for managing config values, extensions, running database migration, purging the cache, and more.
 
-Most operating systems ship with a built in command line application. For Mac OS and Ubuntu it is called "Terminal" and for Windows it is called "Command Prompt". Third party software such as `PuTTY <http://www.putty.org>`_ and `iTerm <https://www.iterm2.com>`_ can also be used.
+Most operating systems ship with a built in command line application. For Mac OS and Ubuntu it is called "Terminal" and for Windows it is called "Command Prompt". Third party software such as `PuTTY <https://www.putty.org>`_ and `iTerm <https://www.iterm2.com>`_ can also be used.
 
 To use phpBB's CLI on a web server, you will need SSH access to your web server. You can find out from your web hosting company if they offer SSH access and how to log into your web server from the CLI.
 
@@ -61,7 +61,7 @@ General options
 Common options that can be used with any of phpBB's CLI commands.
 
 .. csv-table::
-   :header: "Option", "Usage"
+   :header: Option, Usage
    :delim: |
 
    ``--help, -h`` | Display a help message
@@ -111,7 +111,7 @@ The phpBB CLI installer uses a YAML file populated with the data needed to confi
 
             server:
                 cookie_secure: false
-                server_protocol: http://
+                server_protocol: https://
                 force_server_vars: false
                 server_name: localhost
                 server_port: 80

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

@@ -2,7 +2,7 @@
 Database Abstraction Layer
 ==========================
 
-phpBB uses a **D**\ ata\ **B**\ ase **A**\ bstraction **L**\ ayer to access the database instead of directly calling e.g. `mysql_query <http://php.net/manual/en/function.mysql-query.php>`_ functions.
+phpBB uses a **D**\ ata\ **B**\ ase **A**\ bstraction **L**\ ayer to access the database instead of directly calling e.g. `mysql_query <https://php.net/manual/en/function.mysql-query.php>`_ functions.
 You usually access the :abbr:`DBAL (Database Abstraction Layer)` using the global variable ``$db``.
 This variable is included from :class:`common.php` through :class:`includes/compatibility_globals.php`:
 
@@ -49,11 +49,10 @@ 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"
+   :header: Parameter, Usage
    :delim: #
 
    Host # The host of the database. |br| When using config.php you should use $dbhost instead.
@@ -115,10 +114,10 @@ Example:
     // Now run the query...
     $result = $db->sql_query($sql);
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
-   :header: "Parameter", "Usage"
+   :header: Parameter, Usage
    :delim: #
 
    Query Type # Type of query which needs to be created (SELECT, SELECT_DISTINCT)
@@ -155,10 +154,10 @@ Example:
     $sql = 'INSERT INTO ' . USERS_TABLE . ' ' . $db->sql_build_array('INSERT', $data);
     $db->sql_query($sql);
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
-   :header: "Parameter", "Usage"
+   :header: Parameter, Usage
    :delim: #
 
    Query Type # Type of query which needs to be created (UPDATE, INSERT, INSERT_SELECT or SELECT)
@@ -179,10 +178,10 @@ Example:
     	WHERE ' . $db->sql_in_set('user_id', $sql_in);
 
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
-   :header: "Parameter", "Usage"
+   :header: Parameter, Usage
    :delim: |
 
    Column | Name of the sql column that shall be compared
@@ -204,10 +203,10 @@ Example:
     	WHERE post_id = ' . (int) $integer . "
     		AND post_text = '" . $db->sql_escape($string) . "'";
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
-   :header: "Parameter", "Usage"
+   :header: Parameter, Usage
    :delim: |
 
    String | The string that needs to be escaped.
@@ -220,10 +219,10 @@ 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"
+   :header: Parameter, Usage
    :delim: |
 
    Expression | The expression to use. Every wildcard is escaped, except $db->get_any_char() and $db->get_one_char()
@@ -266,10 +265,10 @@ Example:
     	WHERE ' . $db->sql_lower_text('log_data') . ' ' . $like;
     $result = $db->sql_query_limit($sql, 10);
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
-   :header: "Parameter", "Usage"
+   :header: Parameter, Usage
    :delim: |
 
    Column name | The column name to LOWER the value for.
@@ -295,10 +294,10 @@ Example:
     $result = $db->sql_query($sql);
 
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
-   :header: "Parameter", "Usage"
+   :header: Parameter, Usage
    :delim: |
 
    Query | Contains the SQL query which shall be executed
@@ -320,10 +319,10 @@ Example:
     $result = $db->sql_query_limit($sql, $config['topics_per_page'], $start);
 
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
-   :header: "Parameter", "Usage"
+   :header: Parameter, Usage
    :delim: |
 
    Query | Contains the SQL query which shall be executed.
@@ -356,10 +355,10 @@ Example:
     $db->sql_multi_insert(USER_GROUP_TABLE, $sql_ary);
 
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
-   :header: "Parameter", "Usage"
+   :header: Parameter, Usage
    :delim: |
 
    Table name | Table name to run the statements on.
@@ -424,10 +423,10 @@ Example:
     $total_posts = (int) $db->sql_fetchfield('num_posts');
 
 
-Parameters
-^^^^^^^^^^
+.. rubric:: Parameters
+
 .. csv-table::
-   :header: "Parameter", "Usage"
+   :header: Parameter, Usage
    :delim: #
 
    Field # Name of the field that needs to be fetched.
@@ -438,11 +437,10 @@ 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"
+   :header: Parameter, Usage
    :delim: #
 
    Result (Optional) # The result that is being evaluated. |br| This result comes from a call to the sql_query method. |br| If left empty the last result will be called.
@@ -476,11 +474,10 @@ Example with a while-loop:
     	$config[$row['config_name']] = $row['config_value'];
     }
 
+.. rubric:: Parameters
 
-Parameters
-^^^^^^^^^^
 .. csv-table::
-   :header: "Parameter", "Usage"
+   :header: Parameter, Usage
    :delim: #
 
    Result (Optional) # The result that is being evaluated. |br| The result comes from a call to the sql_query method. |br| If left empty the last result will be called.
@@ -489,11 +486,10 @@ 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"
+   :header: Parameter, Usage
    :delim: #
 
    Row number # The number of the row which needs to be found (zero-based).
@@ -519,11 +515,10 @@ 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"
+   :header: Parameter, Usage
    :delim: #
 
    Result (Optional) # The result that is being evaluated. |br| This result comes from a call to the sql_query method. |br| If left empty the last result will be called.

development/development/css/css_guidelines.rst

@@ -323,12 +323,12 @@ Our project makes use of several tools to lint and keep code up to standards.
 
 .. note:: This is used to help automatically re-format your code on-the-fly to meet standards during the build process via ``gulp`` as well as on save in your editor.
 
-.. note:: Our editors of choice are `PhpStorm`_ & `ATOM`_ which provide useful plugins to make use of these tools. Check out the `Editor Setup`_ section of the docs for more information
+.. note:: Our editors of choice are `PhpStorm`_ & `Visual Studio Code`_ which provide useful plugins to make use of these tools. Check out the `Editor Setup`_ section of the docs for more information
 
-.. _stylelint.io: http://www.stylelint.io
+.. _stylelint.io: https://stylelint.io/
 .. _postcss-sorting: https://github.com/hudochenkov/postcss-sorting
 .. _postcss-pxtorem: https://github.com/cuth/postcss-pxtorem
 .. _stylefmt: https://github.com/morishitter/stylefmt
 .. _PhpStorm: https://www.jetbrains.com/phpstorm/
-.. _ATOM: http://www.atom.io
+.. _Visual Studio Code: https://code.visualstudio.com/
 .. _Editor Setup: /editor-setup

development/development/css/css_selectors.rst

@@ -248,9 +248,9 @@ Further Reading
 -  `Writing efficient CSS selectors`_
 
 
-.. _Shoot to kill; CSS selector intent: http://csswizardry.com/2012/07/shoot-to-kill-css-selector-intent/
-.. _‘Scope’ in CSS: http://csswizardry.com/2013/05/scope-in-css/
-.. _Keep your CSS selectors short: http://csswizardry.com/2012/05/keep-your-css-selectors-short/
-.. _About HTML semantics and front-end architecture: http://nicolasgallagher.com/about-html-semantics-front-end-architecture/
-.. _Naming UI components in OOCSS: http://csswizardry.com/2014/03/naming-ui-components-in-oocss/
-.. _Writing efficient CSS selectors: http://csswizardry.com/2011/09/writing-efficient-css-selectors/
+.. _Shoot to kill; CSS selector intent: https://csswizardry.com/2012/07/shoot-to-kill-css-selector-intent/
+.. _‘Scope’ in CSS: https://csswizardry.com/2013/05/scope-in-css/
+.. _Keep your CSS selectors short: https://csswizardry.com/2012/05/keep-your-css-selectors-short/
+.. _About HTML semantics and front-end architecture: https://nicolasgallagher.com/about-html-semantics-front-end-architecture/
+.. _Naming UI components in OOCSS: https://csswizardry.com/2014/03/naming-ui-components-in-oocss/
+.. _Writing efficient CSS selectors: https://csswizardry.com/2011/09/writing-efficient-css-selectors/

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: http://jsfiddle.net/csswizardry/0yb7rque/
-.. _known bug: https://twitter.com/codepo8/status/505004085398224896
-.. _‘Scope’ in CSS: http://csswizardry.com/2013/05/scope-in-css/
-.. _Hacks for dealing with specificity: http://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/css/css_standards.rst

@@ -255,4 +255,4 @@ Preprocessor Comments
 
 With most—if not all—preprocessors, we have the option to write comments that will not get compiled out into our resulting CSS file. As a rule, use these comments to speed up and prevent errors in the minification step.
 
-.. _EditorConfig: http://editorconfig.org/
+.. _EditorConfig: https://editorconfig.org/