Improve documentation with command lines and defaults. (#1415)

* Improve documentation with command lines and defaults.

The advanced documentation coverage skipped the simple approach and didn't
explain fully what to do with the sample commands.

Fixes #1413.

* Fix docs indentation in the MySQL connection string options.

* Desultory docs and docs config fixes.

Author: dimitri

docs/conf.py

@@ -92,11 +92,11 @@
 #
 # html_theme_options = {}
 html_theme_options = {
-    'github_user': 'dimitri',
-    'github_repo': 'pgloader',
-    'description': 'your migration companion',
-    'travis_button': True,
-    'show_related': True,
+    #'github_user': 'dimitri',
+    #'github_repo': 'pgloader',
+    #'description': 'your migration companion',
+    #'travis_button': True,
+    #'show_related': True,
     #'sidebar_collapse': False,
 }
 

docs/pgloader-usage-examples.rst

@@ -455,6 +455,8 @@ pgloader templating system::
 The mustache templates implementation with OS environment support replaces
 former `GETENV` implementation, which didn't work anyway.
 
+.. _common_clauses:
+
 Common Clauses
 --------------
 

docs/pgloader.rst

@@ -5,7 +5,19 @@ This command instructs pgloader to load data from one or more files contained
 in an archive. Currently the only supported archive format is *ZIP*, and the
 archive might be downloaded from an *HTTP* URL.
 
-Here's an example::
+Using advanced options and a load command file
+----------------------------------------------
+
+The command then would be:
+
+::
+
+   $ pgloader archive.load
+
+And the contents of the ``archive.load`` file could be inspired from the
+following:
+
+::
 
     LOAD ARCHIVE
        FROM /Users/dim/Downloads/GeoLiteCity-latest.zip
@@ -61,7 +73,11 @@ Here's an example::
        FINALLY DO
          $$ create index blocks_ip4r_idx on geolite.blocks using gist(iprange); $$;
 
-The `archive` command accepts the following clauses and options.
+Common Clauses
+--------------
+
+Please refer to :ref:`common_clauses` for documentation about common
+clauses.
 
 Archive Source Specification: FROM
 ----------------------------------

docs/ref/archive.rst

@@ -2,7 +2,20 @@ Loading COPY Formatted Files
 ============================
 
 This commands instructs pgloader to load from a file containing COPY TEXT
-data as described in the PostgreSQL documentation. Here's an example::
+data as described in the PostgreSQL documentation.
+
+Using advanced options and a load command file
+----------------------------------------------
+
+The command then would be:
+
+::
+
+   $ pgloader copy.load
+
+And the contents of the ``copy.load`` file could be inspired from the following:
+
+::
 
     LOAD COPY
          FROM copy://./data/track.copy
@@ -33,7 +46,12 @@ data as described in the PostgreSQL documentation. Here's an example::
             );
          $$;
 
-The `COPY` format command accepts the following clauses and options.
+
+Common Clauses
+--------------
+
+Please refer to :ref:`common_clauses` for documentation about common
+clauses.
 
 COPY Formatted Files Source Specification: FROM
 -----------------------------------------------

docs/ref/copy.rst

@@ -1,8 +1,23 @@
 Loading CSV data
 ================
 
-This command instructs pgloader to load data from a `CSV` file. Here's an
-example::
+This command instructs pgloader to load data from a `CSV` file. Because of
+the complexity of guessing the parameters of a CSV file, it's simpler to
+instruct pgloader with how to parse the data in there, using the full
+pgloader command syntax and CSV specifications as in the following example.
+
+Using advanced options and a load command file
+----------------------------------------------
+
+The command then would be:
+
+::
+
+   $ pgloader csv.load
+
+And the contents of the ``csv.load`` file could be inspired from the following:
+
+::
 
     LOAD CSV
        FROM 'GeoLiteCity-Blocks.csv' WITH ENCODING iso-646-us
@@ -25,7 +40,11 @@ example::
 
         SET work_mem to '32 MB', maintenance_work_mem to '64 MB';
 
-The `csv` format command accepts the following clauses and options.
+Common Clauses
+--------------
+
+Please refer to :ref:`common_clauses` for documentation about common
+clauses.
 
 CSV Source Specification: FROM
 ------------------------------

docs/ref/csv.rst

@@ -5,17 +5,33 @@ This command instructs pgloader to load data from a `DBF` file. A default
 set of casting rules are provided and might be overloaded and appended to by
 the command.
 
+Using advanced options and a load command file
+----------------------------------------------
+
 Here's an example with a remote HTTP source and some user defined casting
-rules::
+rules. The command then would be:
+
+::
+
+   $ pgloader dbf.load
+
+And the contents of the ``dbf.load`` file could be inspired from the following:
+
+::
 
     LOAD DBF
-	    FROM http://www.insee.fr/fr/methodes/nomenclatures/cog/telechargement/2013/dbf/reg2013.dbf
+        FROM http://www.insee.fr/fr/methodes/nomenclatures/cog/telechargement/2013/dbf/reg2013.dbf
         INTO postgresql://user@localhost/dbname
         WITH truncate, create table
         CAST column reg2013.region to integer,
              column reg2013.tncc to smallint;
 
-The `dbf` format command accepts the following clauses and options.
+
+Common Clauses
+--------------
+
+Please refer to :ref:`common_clauses` for documentation about common
+clauses.
 
 DBF Source Specification: FROM
 ------------------------------

docs/ref/dbf.rst

@@ -2,7 +2,20 @@ Loading Fixed Cols File Formats
 ===============================
 
 This command instructs pgloader to load data from a text file containing
-columns arranged in a *fixed size* manner. Here's an example::
+columns arranged in a *fixed size* manner.
+
+Using advanced options and a load command file
+----------------------------------------------
+
+The command then would be:
+
+::
+
+   $ pgloader fixed.load
+
+And the contents of the ``fixed.load`` file could be inspired from the following:
+
+::
 
     LOAD FIXED
          FROM inline
@@ -41,7 +54,16 @@ columns arranged in a *fixed size* manner. Here's an example::
       2345609872014092914371500                 
       2345678902014092914371520
 
-The `fixed` format command accepts the following clauses and options.
+Note that the example comes from the test suite of pgloader, where we use
+the advanced feature ``FROM inline`` that allows embedding the source data
+within the command file. In most cases a more classic FROM clause loading
+the data from a separate file would be used.
+
+Common Clauses
+--------------
+
+Please refer to :ref:`common_clauses` for documentation about common
+clauses.
 
 Fixed File Format Source Specification: FROM
 --------------------------------------------