From b10e57099d2e3b35ecd79ba40dc724dc41c5aaa5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= Date: Mon, 17 Oct 2016 16:47:23 +0200 Subject: [PATCH 1/6] Add documentation checks to be executed in Travis CI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Validate all internal references - Validate parse errors - Validate external links Signed-off-by: Michal Čihař --- .travis.yml | 2 ++ test/ci-docs | 30 ++++++++++++++++++++++++++++++ test/ci-install-docs | 6 ++++++ 3 files changed, 38 insertions(+) create mode 100755 test/ci-docs create mode 100755 test/ci-install-docs diff --git a/.travis.yml b/.travis.yml index 2a683994b9..6577fca01d 100644 --- a/.travis.yml +++ b/.travis.yml @@ -56,6 +56,8 @@ matrix: env: CI_MODE=selenium - php: "7.0" env: CI_MODE=release + - php: "7.0" + env: CI_MODE=docs cache: directories: - $HOME/.composer/cache/ diff --git a/test/ci-docs b/test/ci-docs new file mode 100755 index 0000000000..96a9d588a1 --- /dev/null +++ b/test/ci-docs @@ -0,0 +1,30 @@ +#!/bin/bash + +set -e + +travis_retry() { + local result=0 + local count=1 + while [ $count -le 3 ]; do + [ $result -ne 0 ] && { + echo -e "\n${ANSI_RED}The command \"$@\" failed. Retrying, $count of 3.${ANSI_RESET}\n" >&2 + } + "$@" + result=$? + [ $result -eq 0 ] && break + count=$(($count + 1)) + sleep 1 + done + + [ $count -gt 3 ] && { + echo -e "\n${ANSI_RED}The command \"$@\" failed 3 times.${ANSI_RESET}\n" >&2 + } + + return $result +} + +# Build documentation with warnings treated as errors +make -C doc html SPHINXOPTS='-n -W -a' + +# Check external links +travis_retry make -C doc linkcheck diff --git a/test/ci-install-docs b/test/ci-install-docs new file mode 100755 index 0000000000..4e97b9798c --- /dev/null +++ b/test/ci-install-docs @@ -0,0 +1,6 @@ +#!/bin/sh + +# We use 1.5 to be able to deal with gzip only sites in linkcheck (such as tcpdf.org) + +pip install --user 'Sphinx>=1.5a2' + From 4fc27b8e8ebdf5debdb478a1c9536eb05957e846 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= Date: Tue, 18 Oct 2016 09:48:58 +0200 Subject: [PATCH 2/6] Compatibility with Sphinx 1.4 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/sphinx-doc/sphinx/issues/2673 Signed-off-by: Michal Čihař --- doc/_ext/configext.py | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/doc/_ext/configext.py b/doc/_ext/configext.py index 021b4505cc..7ed61fc0de 100644 --- a/doc/_ext/configext.py +++ b/doc/_ext/configext.py @@ -52,21 +52,21 @@ class ConfigOption(ObjectDescription): # Generic index entries indexentry = self.indextemplate % (name,) self.indexnode['entries'].append((indextype, indexentry, - targetname, targetname)) + targetname, targetname, None)) self.indexnode['entries'].append((indextype, name, - targetname, targetname)) + targetname, targetname, None)) # Server section if targetparts[0] == 'Servers' and len(targetparts) > 1: indexname = ', '.join(targetparts[1:]) self.indexnode['entries'].append((indextype, 'server configuration; %s' % indexname, - targetname, targetname)) + targetname, targetname, None)) self.indexnode['entries'].append((indextype, indexname, - targetname, targetname)) + targetname, targetname, None)) else: indexname = ', '.join(targetparts) self.indexnode['entries'].append((indextype, indexname, - targetname, targetname)) + targetname, targetname, None)) self.env.domaindata['config']['objects'][self.objtype, name] = \ self.env.docname, targetname @@ -84,8 +84,8 @@ class ConfigSectionXRefRole(XRefRole): tgtid = 'index-%s' % env.new_serialno('index') indexnode = addnodes.index() indexnode['entries'] = [ - ('single', varname, tgtid, varname), - ('single', 'configuration section; %s' % varname, tgtid, varname) + ('single', varname, tgtid, varname, None), + ('single', 'configuration section; %s' % varname, tgtid, varname, None) ] targetnode = nodes.target('', '', ids=[tgtid]) document.note_explicit_target(targetnode) @@ -118,7 +118,7 @@ class ConfigSection(ObjectDescription): indextype = 'single' indexentry = self.indextemplate % (name,) self.indexnode['entries'].append((indextype, indexentry, - targetname, targetname)) + targetname, targetname, None)) self.env.domaindata['config']['objects'][self.objtype, name] = \ self.env.docname, targetname @@ -135,8 +135,8 @@ class ConfigOptionXRefRole(XRefRole): tgtid = 'index-%s' % env.new_serialno('index') indexnode = addnodes.index() indexnode['entries'] = [ - ('single', varname, tgtid, varname), - ('single', 'configuration option; %s' % varname, tgtid, varname) + ('single', varname, tgtid, varname, None), + ('single', 'configuration option; %s' % varname, tgtid, varname, None) ] targetnode = nodes.target('', '', ids=[tgtid]) document.note_explicit_target(targetnode) @@ -185,4 +185,3 @@ class ConfigFileDomain(Domain): def setup(app): app.add_domain(ConfigFileDomain) - From 21beba716a10ccdfb552eaeecca1496f993f8d43 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= Date: Tue, 18 Oct 2016 09:55:15 +0200 Subject: [PATCH 3/6] Fix missing references in docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michal Čihař --- doc/charts.rst | 2 +- doc/config.rst | 15 ++++++++++++++- doc/setup.rst | 2 +- 3 files changed, 16 insertions(+), 3 deletions(-) diff --git a/doc/charts.rst b/doc/charts.rst index 0839fbf293..a64281c3a5 100644 --- a/doc/charts.rst +++ b/doc/charts.rst @@ -34,7 +34,7 @@ Pie chart Query results for a simple pie chart can be generated with: -.. code-block:: sql +.. code-block:: mysql SELECT 'Food' AS 'expense',     1250 AS 'amount' UNION diff --git a/doc/config.rst b/doc/config.rst index e5a2696d72..0cf96db3e9 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -833,7 +833,7 @@ Server connection settings ``pma__column_info``) * to update your PRE-2.5.0 Column\_comments table use this: and remember that the Variable in :file:`config.inc.php` has been renamed from - :config:option:`$cfg['Servers'][$i]['column\_comments']` to + :samp:`$cfg['Servers'][$i]['column\_comments']` to :config:option:`$cfg['Servers'][$i]['column\_info']` .. code-block:: mysql @@ -2291,7 +2291,13 @@ Export and import settings * ``custom-no-form`` same as ``custom`` but does not display the option of using quick export +.. config:option:: $cfg['Export']['charset'] + :type: string + :default: ``''`` + + Defines charset for generated export. By default no charset conversion is + done assuming UTF-8. .. config:option:: $cfg['Import'] @@ -2302,6 +2308,13 @@ Export and import settings items are similar to texts seen on import page, so you can easily identify what they mean. +.. config:option:: $cfg['Import']['charset'] + + :type: string + :default: ``''`` + + Defines charset for import. By default no charset conversion is done + assuming UTF-8. Tabs display settings --------------------- diff --git a/doc/setup.rst b/doc/setup.rst index 48d54c204a..c6c860571f 100644 --- a/doc/setup.rst +++ b/doc/setup.rst @@ -209,7 +209,7 @@ By default, :ref:`cookie` is used, but if :envvar:`PMA_USER` and The credentials you need to login are stored in the MySQL server, in case of Docker image there are various ways to set it (for example - :envvar:`MYSQL_ROOT_PASSWORD` when starting MySQL container). Please check + :samp:`MYSQL_ROOT_PASSWORD` when starting MySQL container). Please check documentation for `MariaDB container `_ or `MySQL container `_. From fffbcd1969faa3e2d98e03ce24b5ed4432ce3024 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= Date: Tue, 18 Oct 2016 10:03:52 +0200 Subject: [PATCH 4/6] Avoid using non breakable space in code samples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - It's not possible to copy and paste it then - It's not possible to use syntax highlighting on these Signed-off-by: Michal Čihař --- doc/charts.rst | 42 +++++++++++++++++++++--------------------- doc/config.rst | 4 +++- doc/faq.rst | 28 ++++++++++++++++------------ doc/setup.rst | 4 ++-- 4 files changed, 42 insertions(+), 36 deletions(-) diff --git a/doc/charts.rst b/doc/charts.rst index a64281c3a5..4117f9c682 100644 --- a/doc/charts.rst +++ b/doc/charts.rst @@ -34,13 +34,13 @@ Pie chart Query results for a simple pie chart can be generated with: -.. code-block:: mysql +.. code-block:: sql - SELECT 'Food' AS 'expense',  -    1250 AS 'amount' UNION - SELECT 'Accommodation', 500 UNION - SELECT 'Travel', 720 UNION - SELECT 'Misc', 220 + SELECT 'Food' AS 'expense', + 1250 AS 'amount' UNION + SELECT 'Accommodation', 500 UNION + SELECT 'Travel', 720 UNION + SELECT 'Misc', 220 And the result of this query is: @@ -69,14 +69,14 @@ Query results for a simple bar or column chart can be generated with: .. code-block:: sql - SELECT  -    'ACADEMY DINOSAUR' AS 'title', -    0.99 AS 'rental_rate', -    20.99 AS 'replacement_cost' UNION - SELECT 'ACE GOLDFINGER', 4.99, 12.99 UNION - SELECT 'ADAPTATION HOLES', 2.99, 18.99 UNION - SELECT 'AFFAIR PREJUDICE', 2.99, 26.99 UNION - SELECT 'AFRICAN EGG', 2.99, 22.99 + SELECT + 'ACADEMY DINOSAUR' AS 'title', + 0.99 AS 'rental_rate', + 20.99 AS 'replacement_cost' UNION + SELECT 'ACE GOLDFINGER', 4.99, 12.99 UNION + SELECT 'ADAPTATION HOLES', 2.99, 18.99 UNION + SELECT 'AFFAIR PREJUDICE', 2.99, 26.99 UNION + SELECT 'AFRICAN EGG', 2.99, 22.99 And the result of this query is: @@ -116,13 +116,13 @@ Query results for a simple line, spline or timeline chart can be generated with: .. code-block:: sql - SELECT  -    DATE('2006-01-08') AS 'date',  -    2056 AS 'revenue', -    1378 AS 'cost' UNION - SELECT DATE('2006-01-09'), 1898, 2301 UNION - SELECT DATE('2006-01-15'), 1560, 600 UNION - SELECT DATE('2006-01-17'), 3457, 1565 + SELECT + DATE('2006-01-08') AS 'date', + 2056 AS 'revenue', + 1378 AS 'cost' UNION + SELECT DATE('2006-01-09'), 1898, 2301 UNION + SELECT DATE('2006-01-15'), 1560, 600 UNION + SELECT DATE('2006-01-17'), 3457, 1565 And the result of this query is: diff --git a/doc/config.rst b/doc/config.rst index 0cf96db3e9..9adccd9fdb 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -3224,7 +3224,9 @@ Google Cloud SQL with SSL To connect to Google Could SQL, you currently need to disable certificate verification. This is caused by the certficate being issued for CN matching your instance name, but you connect to an IP address and PHP tries to match -these two. With verfication you end up with error message like:: +these two. With verfication you end up with error message like: + +.. code-block:: text Peer certificate CN=`api-project-851612429544:pmatest' did not match expected CN=`8.8.8.8' diff --git a/doc/faq.rst b/doc/faq.rst index 86b9dbc5c4..6e29b35fd2 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -254,8 +254,8 @@ current setup): [PHP] - ; Directory in which the loadable extensions (modules) reside. - extension_dir = "C:/Apache2/modules/php/ext" + ; Directory in which the loadable extensions (modules) reside. + extension_dir = "C:/Apache2/modules/php/ext" The :file:`php.ini` can be loaded from several locations (especially on Windows), so please check you're updating the correct one. If using Apache, you @@ -263,14 +263,14 @@ can tell it to use specific path for this file using ``PHPIniDir`` directive: .. code-block:: apache - LoadFile "C:/php/php5ts.dll" - LoadModule php5_module "C:/php/php5apache2_2.dll" + LoadFile "C:/php/php5ts.dll" + LoadModule php5_module "C:/php/php5apache2_2.dll" -     PHPIniDir "C:/PHP" -     -        AddType text/html .php -        AddHandler application/x-httpd-php .php -     + PHPIniDir "C:/PHP" + + AddType text/html .php + AddHandler application/x-httpd-php .php + In some rare cases this problem can be also caused by other extensions loaded @@ -373,7 +373,7 @@ This can happen due to a MySQL bug when having database / table names with upper case characters although ``lower_case_table_names`` is set to 1. To fix this, turn off this directive, convert all database and table names to lower case and turn it on again. Alternatively, -there's a bug-fix available starting with MySQL 3.23.56 / +there's a bug-fix available starting with MySQL 3.23.56 / 4.0.11-gamma. .. _faq1_29: @@ -1351,7 +1351,9 @@ browser cache to see if the problem goes away. 5.20 I get errors about violating Content Security Policy. ---------------------------------------------------------- -If you see errors like:: +If you see errors like: + +.. code-block:: text Refused to apply inline style because it violates the following Content Security Policy directive @@ -1376,7 +1378,9 @@ Programs known to cause these kind of errors: 5.21 I get erros about potentnionally unsafe operation when browsing table or executing SQL query. -------------------------------------------------------------------------------------------------- -If you see errors like:: +If you see errors like: + +.. code-block:: text A potentially unsafe operation has been detected in your request to this site. diff --git a/doc/setup.rst b/doc/setup.rst index c6c860571f..2a28588c03 100644 --- a/doc/setup.rst +++ b/doc/setup.rst @@ -318,8 +318,8 @@ simple configuration may look like this: $i=0; $i++; $cfg['Servers'][$i]['auth_type'] = 'cookie'; - // if you insist on "root" having no password: - // $cfg['Servers'][$i]['AllowNoPasswordRoot'] = true; ` + // if you insist on "root" having no password: + // $cfg['Servers'][$i]['AllowNoPasswordRoot'] = true; ` ?> Or, if you prefer to not be prompted every time you log in: From 855899628a33a1d2d74bc0ef128f026e59d5457f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= Date: Tue, 18 Oct 2016 10:04:53 +0200 Subject: [PATCH 5/6] Specify we are using MySQL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michal Čihař --- doc/charts.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/charts.rst b/doc/charts.rst index 4117f9c682..618f0554ca 100644 --- a/doc/charts.rst +++ b/doc/charts.rst @@ -34,7 +34,7 @@ Pie chart Query results for a simple pie chart can be generated with: -.. code-block:: sql +.. code-block:: mysql SELECT 'Food' AS 'expense', 1250 AS 'amount' UNION @@ -67,7 +67,7 @@ Both bar charts and column chats support stacking. Upon selecting one of these t Query results for a simple bar or column chart can be generated with: -.. code-block:: sql +.. code-block:: mysql SELECT 'ACADEMY DINOSAUR' AS 'title', @@ -114,7 +114,7 @@ These charts can be used to illustrate trends in underlying data. Spline charts Query results for a simple line, spline or timeline chart can be generated with: -.. code-block:: sql +.. code-block:: mysql SELECT DATE('2006-01-08') AS 'date', From 8051ae981b87b9a1bc62a45c8984a909cae224fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Michal=20=C4=8Ciha=C5=99?= Date: Tue, 18 Oct 2016 10:41:47 +0200 Subject: [PATCH 6/6] Install requests[security] for SNI support MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michal Čihař --- test/ci-install-docs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/ci-install-docs b/test/ci-install-docs index 4e97b9798c..624e0084f1 100755 --- a/test/ci-install-docs +++ b/test/ci-install-docs @@ -2,5 +2,5 @@ # We use 1.5 to be able to deal with gzip only sites in linkcheck (such as tcpdf.org) -pip install --user 'Sphinx>=1.5a2' +pip install --user 'Sphinx>=1.5a2' 'requests[security]'