diff --git a/docs/how_to/additional_formatting.md b/docs/how_to/additional_formatting.md index 34d3c9e9..e3a8cf50 100644 --- a/docs/how_to/additional_formatting.md +++ b/docs/how_to/additional_formatting.md @@ -1,13 +1,19 @@ # Add additional formatting -There may be specific user needs or organisational reasons calling for -formatting other than the `gptables` defaults. A wide range of options are possible -with the `gptable.GPTable(..., additional_formatting = ...)` parameter. See the [XlsxWriter documentation](https://xlsxwriter.readthedocs.io/format.html#the-format-class) for the full options. +There may be specific user needs or organisational reasons requiring +formatting other than the `gptables` defaults. If this is required regularly, consider +the use of a [theme](custom_theme.md). + +A wide range of options are possible +with the `gptable.GPTable(..., additional_formatting = ...)` parameter. See the [XlsxWriter documentation](https://xlsxwriter.readthedocs.io/format.html#format-methods-and-format-properties) for all formatting options. !!! warning "Consider accessibility implications to formatting changes" Additional formatting changes the `gptables` defaults, which can introduce accessibility issues. Refer to the Releasing statistics in spreadsheets [guidance](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/) and consider user needs regarding accessiblity before adjusting the formatting. +The sample code can be run from thes +[examples](https://github.com/ONSdigital/gptables/tree/main/gptables/examples) folder. + ## Using `additional_formatting` The `gptable.GPTable(..., additional_formatting = ...)` parameter allows for specifying @@ -17,9 +23,6 @@ columns, rows, and/or cells and the corresponding formatting changes to make. There are some conflicts between additional formatting options, for example wrapping and shrinking text. Outputs should be reviewed for correctness. -Columns can be referenced by name or number. Rows may only be referenced by number, with `-1` -corresponding to the last row. Column and row numbers include indexes and column headings. Numeric indexing refers to position within the table, not the position in the output Excel sheet. Cell formatting takes highest precedence, followed by row formatting, and finally column formatting. - The option of what to format is specified, followed by the specific columns, rows, or cells, and then the formatting changes. To change the properties of columns called Species and Island to be center-aligned and italic, for example: @@ -37,6 +40,8 @@ sample_additional_formatting = [ } ] ``` +Columns can be referenced by name or number. Rows may only be referenced by number, with `-1` +corresponding to the last row. Column and row numbers include indices and column headings. Numeric indexing refers to position within the table, not the position in the output Excel sheet. Cell formatting takes highest precedence, followed by row formatting, and finally column formatting. Multiple selections of columns, rows, and cells can be made in a single `additional_formatting` list. @@ -71,11 +76,10 @@ italicisation of two columns, left bordering on the 4th column, and indentation ??? "Using additional formatting" ```python - from pathlib import Path import pandas as pd import gptables as gpt - penguins_data = pd.read_csv("spenguins.csv") + penguins_data = pd.read_csv("penguins.csv") penguins_additional_formatting = [ { @@ -115,18 +119,18 @@ italicisation of two columns, left bordering on the 4th column, and indentation penguins_sheets = {"Penguins": penguins_table} wb = gpt.produce_workbook( - filename="gptables_additional_formatting_example.xlsx", + filename="gpt_additional_formatting.xlsx", sheets=penguins_sheets ) wb.close() ``` -![](../static/additional_formatting.png) +![](../static/howto_additional_formatting.png) ## Formatting text Formatting can also be applied to the text in `title`, `subtitles`, `scope`, `source` -and `legend` elements, without using `additional_formatting`. Avoid using text formatting to represent data or important information, as most formatting is neither accessible nor machine readable. +and `legend` elements without using `additional_formatting`. Avoid using text formatting to represent data or important information, as most formatting is neither accessible nor machine readable. Instead of a string, provide a list of strings and dictionaries containing valid [XlsxWriter format properties](https://xlsxwriter.readthedocs.io/format.html#format-methods-and-format-properties) and values to the relevant parameter. The formatting defined in these dictionaries will be applied to the @@ -139,11 +143,12 @@ formatted_subtitles = [ ] ``` +![](../static/howto_additional_formatting_text.png) + This is combined with a basic example below in an extendable tab. ??? "Formatting text" ```python - from pathlib import Path import pandas as pd import gptables as gpt @@ -174,6 +179,7 @@ This is combined with a basic example below in an extendable tab. This formatting is applied in addition to the formatting of that element specified in the [`Theme`](../api/classes/theme.md). + !!! warning "Formatting of note references and links" Text formatting is not currently supported if the cell also contains note references or links. This may be changed in the future if there is @@ -208,91 +214,3 @@ ws.set_column( 2, 3, 10, italic_format ) ``` - -### Formatting methods - -The following tables show the Excel format categories, along with an example demonstrating the syntax required -for use in gptables. Some formatting methods use indexing to map to Excel’s built-in formats. This information -can be found in the applicable sections below. - -#### Font formatting - -This table demonstrates the font formatting methods available. You can find all options -for [underline styles in the XlsxWriter documentation](https://xlsxwriter.readthedocs.io/format.html#format-set-underline). - -| Description | Example usage | -|-----------------|-----------------------------------------------------------------------------------------| -| Font type | {“font_name”: “Arial”} | -| Font size | {“font_size”: 30} | -| Font colour | {“font_color”: “red”} | -| Bold | {“bold”: True} | -| Italic | {“italic”: True} | -| Underline | {“underline”: 1} | -| Strikeout | {“font_strikeout”: True} | -| Super/Subscript | {“font_script”: 1} # Superscript


{“font_script”: 2} # Subscript

| - -#### Number formatting - -This table demonstrates how to set the numeric format using indexing and string arguments. You can find all -options for [numeric formats in the XlsxWriter documentation](https://xlsxwriter.readthedocs.io/format.html#format-set-num-format). - -| Description | Example usage | -|----------------|-------------------------------------------------------------------------------------------------------| -| Numeric format | {“num_format”: 1} # Format index


{“num_format”: “d mmm yyyy”} # Format string

| - -#### Protection formatting - -This table demonstrates the protection methods available. - -| Description | Example usage | -|---------------|------------------| -| Lock cells | {“locked”: True} | -| Hide formulas | {“hidden”: True} | - -#### Alignment formatting - -This table demonstrates the alignment formatting options available. You can find all options for -[horizontal and vertical alignment in the XlsxWriter documentation](https://xlsxwriter.readthedocs.io/format.html#format-set-align). - -| Description | Example usage | -|------------------|-----------------------------| -| Horizontal align | {“align”: “center”} | -| Vertical align | {“align”: “vcenter”} | -| Rotation | {“rotation”: 30} | -| Text wrap | {“text_wrap”: True} | -| Center across | {“set_center_across”: True} | -| Indentation | {“indentation”:2} | -| Shrink to fit | {“shrink”: True} | - -#### Pattern formatting - -This table demonstrates the pattern formatting options available. - -| Description | Example usage | -|-------------------|-----------------------| -| Cell pattern | {“pattern”: 1} | -| Background colour | {“bg_color”: “white”} | -| Foreground colour | {“fg_color”: “white”} | - -#### Border formatting - -This table demonstrates the border formatting options available. You can find all options -for [border styles in the XlsxWriter documentation](https://xlsxwriter.readthedocs.io/format.html#format-set-border). - -| Description | Example usage | -|---------------|----------------------------| -| Cell border | {“border”: 1} | -| Bottom border | {“bottom”: 1} | -| Top border | {“top”: 1} | -| Left border | {“left”: 1} | -| Right border | {“right”: 1} | -| Border colour | {“border_color”: “red”} | -| Bottom colour | {“bottom_color”:”#FF0000”} | -| Top colour | {“top_color”: “red”} | -| Left colour | {“left_color”: “#FF0000”} | -| Right colour | {“right_color”: “red”} | - -For any formatting beyond this, if the package should support it then please raise an issue -or create a pull request. Otherwise, you will need to modify the underlying -[`GPWorkbook`](../api/classes/gpworkbook.md) or [`GPWorksheet`](../api/classes/gpworksheet.md) objects -before they are written to Excel. diff --git a/docs/how_to/custom_theme.md b/docs/how_to/custom_theme.md index 8634ed83..fb050562 100644 --- a/docs/how_to/custom_theme.md +++ b/docs/how_to/custom_theme.md @@ -1,6 +1,6 @@ # Custom themes with `gptables` -It might be necessary to diverge from the `gptables` defaults, for example for organisational +It might be necessary to diverge from the `gptables` defaults for organisational needs or user requirements. Where this is required regularly or across multiple teams, it can be helpful for reproducibility and code readability to create a custom theme as opposed to supplying an `additional_formatting` argument to `GPTable`. @@ -10,11 +10,10 @@ an `additional_formatting` argument to `GPTable`. Refer to the Releasing statistics in spreadsheets [guidance](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/) and consider user needs regarding accessiblity before adjusting the formatting. -The code to reproduce these sheets can be found in the examples folder. +The sample code can be run from the +[examples](https://github.com/ONSdigital/gptables/tree/main/gptables/examples) folder. -## Using custom themes - -The theme parameter in `gptables.write_workbook()` can be either a folder or a .yaml file. +## Global formatting A .yaml can reformat settings across the whole workbook from global settings, as well as specified elements of the sheet. A basic example is shown below, where the order in which elements @@ -42,7 +41,7 @@ description_order: - scope ``` -The path to the file or folder is supplied to the theme argument of `gptables.write_workbook()` +The path to the theme file or folder is supplied to the theme argument of `gptables.write_workbook()` inside of `gptables.Theme()`: ```python @@ -60,9 +59,8 @@ This is shown to have changed text colours and sizes as compared to the `gptable This is combined into an extendible code block below. -??? note "Basic usage of custom themes" +??? note "global formatting" ```python - from pathlib import Path import pandas as pd import gptables as gpt @@ -81,13 +79,15 @@ This is combined into an extendible code block below. penguins_sheets = {"Penguins": penguins_table} gpt.write_workbook( - filename="gptables_theme_basic.xlsx", + filename="gpt_custom_theme.xlsx", sheets=penguins_sheets, theme=gpt.Theme(example_theme_basic.yaml), contentsheet_options={"additional_elements": ["subtitles", "scope"]}, ) ``` +## Element-wise formatting + Theme files can also be used to modify specific elements, such as the titles and subtitles on the cover: @@ -117,3 +117,6 @@ This is shown to have formatted the sizes of the cover elements, with the global dictating the other font sizes and colour throughout the workbook. ![](../static/howto_theme_cover.png) + +Additional options available for element-wise formatting can be found in the +[theme](https://github.com/ONSdigital/gptables/blob/main/gptables/themes/gptheme.yaml) file. diff --git a/docs/how_to/customisation.md b/docs/how_to/customisation.md deleted file mode 100644 index 166f523c..00000000 --- a/docs/how_to/customisation.md +++ /dev/null @@ -1,4 +0,0 @@ -# Customisation with gptables - -There are limited customisation options with the gptables on account of aiming -to follow the Analysis Function Releasing statistics in spreadsheets [guidance](https://analysisfunction.civilservice.gov.uk/policy-store/releasing-statistics-in-spreadsheets/). diff --git a/docs/how_to/in_r.md b/docs/how_to/in_r.md deleted file mode 100644 index 157b5df0..00000000 --- a/docs/how_to/in_r.md +++ /dev/null @@ -1,6 +0,0 @@ -## R Usage - -Use of `gptables` in R requires use of python via the [reticulate](https://rstudio.github.io/reticulate/) package. - -However we recommend use of the [aftables](https://github.com/best-practice-and-impact/aftables) -R package, maintained by the Presentation Champions Data Visualisation Tools subgroup. diff --git a/docs/index.md b/docs/index.md index a67df319..823dbd1f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,6 +27,7 @@ Get in touch at [ASAP@ons.gov.uk](mailto:ASAP@ons.gov.uk) if you use `gptables` Got a feature request, or found a bug? Raise an [issue](https://github.com/ONSdigital/gptables/issues) on GitHub. ## Related Packages +`gptables` is built on top of [`XlsxWriter`](https://xlsxwriter.readthedocs.io/index.html), bringing with it much of the `XlsxWriter` functionality. Users may also be interested in [aftables](https://best-practice-and-impact.github.io/aftables/), an R native equivalent to `gptables`, and [csvcubed](https://onsdigital.github.io/csvcubed-docs/external/), a package for turning data and metadata into machine-readable CSV-W files. diff --git a/docs/static/additional_formatting.png b/docs/static/howto_additional_formatting.png similarity index 52% rename from docs/static/additional_formatting.png rename to docs/static/howto_additional_formatting.png index 6bdbc970..ec458929 100644 Binary files a/docs/static/additional_formatting.png and b/docs/static/howto_additional_formatting.png differ diff --git a/docs/static/howto_additional_formatting_text.png b/docs/static/howto_additional_formatting_text.png new file mode 100644 index 00000000..1c41dbcd Binary files /dev/null and b/docs/static/howto_additional_formatting_text.png differ diff --git a/docs/static/howto_theme_basic.png b/docs/static/howto_theme_basic.png index b804e66e..254707e8 100644 Binary files a/docs/static/howto_theme_basic.png and b/docs/static/howto_theme_basic.png differ diff --git a/docs/static/howto_theme_cover.png b/docs/static/howto_theme_cover.png index 86d953ef..7994814a 100644 Binary files a/docs/static/howto_theme_cover.png and b/docs/static/howto_theme_cover.png differ diff --git a/gptables/examples/how_to_theme_basic.py b/gptables/examples/how_to_custom_theme.py similarity index 93% rename from gptables/examples/how_to_theme_basic.py rename to gptables/examples/how_to_custom_theme.py index b48f516c..7debdd75 100644 --- a/gptables/examples/how_to_theme_basic.py +++ b/gptables/examples/how_to_custom_theme.py @@ -19,7 +19,7 @@ penguins_sheets = {"Penguins": penguins_table} if __name__ == "__main__": - output_path = parent_dir / "gptables_theme_basic.xlsx" + output_path = parent_dir / "gpt_custom_theme.xlsx" theme_path = str(Path(__file__).parent.parent / "themes/example_theme_basic.yaml") gpt.write_workbook( filename=output_path, diff --git a/gptables/examples/how_to_theme_cover.py b/gptables/examples/how_to_theme_cover.py index 552ba06f..02a9c955 100644 --- a/gptables/examples/how_to_theme_cover.py +++ b/gptables/examples/how_to_theme_cover.py @@ -44,7 +44,7 @@ ) if __name__ == "__main__": - output_path = parent_dir / "gptables_theme_cover.xlsx" + output_path = parent_dir / "gpt_theme_cover.xlsx" theme_path = str(Path(__file__).parent.parent / "themes/example_theme_cover.yaml") gpt.write_workbook( filename=output_path, diff --git a/gptables/examples/howto_additional_formatting.py b/gptables/examples/howto_additional_formatting.py index 866c88f9..c910e1dd 100644 --- a/gptables/examples/howto_additional_formatting.py +++ b/gptables/examples/howto_additional_formatting.py @@ -47,7 +47,7 @@ penguins_sheets = {"Penguins": penguins_table} if __name__ == "__main__": - output_path = parent_dir / "gptables_additional_formatting.xlsx" + output_path = parent_dir / "gpt_additional_formatting.xlsx" wb = gpt.produce_workbook(filename=output_path, sheets=penguins_sheets) wb.close() print("Output written at: ", output_path) diff --git a/mkdocs.yml b/mkdocs.yml index b0ba9130..19c0b560 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,11 +13,8 @@ nav: - Tutorial: getting_started/tutorial.md - Table elements: getting_started/elements.md - How to: - - Multiple sheets: how_to/multiple_sheets.md - #- Customise sheets: how_to/customisation.md - Add additional formatting: how_to/additional_formatting.md - Add a custom theme: how_to/custom_theme.md - - Use in R: how_to/in_r.md - API: - API reference: api/api_reference.md - Functions: