Merge pull request MultiQC#1938 from ewels/config-table-docs

Improve docs about customising tables from the config

docs/core/reports/customisation.md

@@ -528,20 +528,24 @@ custom_plot_config:
 Much like with the custom plot config above, you can override almost any configuration options for tables.
 To see what's available, read the documentation about [Creating a table](#creating-a-table) below.
 
-Tables have configuration at two levels. Table-wide configs are the same as plot configs and can
-be overridden with `custom_plot_config` as described above.
+Tables have configuration at two levels:
 
-Headers have their own configuration which can be overriden with `custom_table_header_config`.
+1. Entire table
+   - Affects all columns and data. These configs are the same as _plot configs_ and can be overridden with `custom_plot_config` as described in the [Customising plots](#customising-plots) section above.
+2. Specific columns
+   - Table columns (headers) have their own configuration scope:`custom_table_header_config`. See below.
 
-Examples are often more useful for this kind of thing than words, so here are a few:
+### Config for an entire table
 
-For the Picard HSMetrics table, we can use a custom table header for the first column
-and change the default minimum value for the colour scale for all columns:
+Here we are customising the _Picard HSMetrics_ table.
+We're setting a non-standard title for the first column (usually _"Sample name"_) and changing the default minimum value for the colour scale for _all_ columns.
 
-> Here `min` is a _header_ config but we're setting it at table config level.
-> This means it will be used as a default for all columns in the table if the module
-> doesn't itself define anything specific for that column.
-> If it does, you need to overwrite that specific column using `custom_table_header_config`
+:::note
+Here `min` is a _header_ config but we're setting it at _table config_ level.
+This means it will be used as a default for all columns in the table if the module
+doesn't itself define anything specific for that column.
+If it does, you need to overwrite that specific column using `custom_table_header_config`.
+:::
 
 ```yaml
 custom_plot_config:
@@ -550,8 +554,9 @@ custom_plot_config:
     min: 1000
 ```
 
-Now for header-specific changes.
-To change the number of decimals used in the General Statistics table for the Qualimap _Mean Coverage_ column:
+### Config for a specific column
+
+To change the number of decimals used in the General Statistics table for the single column _Qualimap: Mean Coverage_:
 
 ```yaml
 custom_table_header_config:
@@ -560,6 +565,18 @@ custom_table_header_config:
       format: "{:,.20f}"
 ```
 
+The first key is the table ID, the second is the header ID for the column you want to change.
+
+:::tip
+The easiest way to find these IDs is by clicking _Configure Columns_ above the table you want to customise.
+
+![Table: configure columns button](../../images/table_configure_columns.png)
+
+The table ID is shown at the top of the modal window. The _ID_ column shows the column (header) ID.
+
+![Table: configure columns button](../../images/table_header_ids.png)
+:::
+
 ### Hiding columns
 
 Report tables such as the General Statistics table can get quite wide. To help with this,

multiqc/plots/table.py

@@ -397,7 +397,7 @@ def make_table(dt):
             <h4 class="modal-title">{title}: Columns</h4>
           </div>
           <div class="modal-body">
-            <p>Uncheck the tick box to hide columns. Click and drag the handle on the left to change order.</p>
+            <p>Uncheck the tick box to hide columns. Click and drag the handle on the left to change order. Table ID: <code>{tid}</code></p>
             <p>
                 <button class="btn btn-default btn-sm mqc_configModal_bulkVisible" data-target="#{tid}" data-action="showAll">Show All</button>
                 <button class="btn btn-default btn-sm mqc_configModal_bulkVisible" data-target="#{tid}" data-action="showNone">Show None</button>