Updates to documentation primarily

CHANGES.md

@@ -8,6 +8,7 @@ New features
 - Added a medium resolution style sheet.
 - PlotLabeller context manager to apply axes formatting to new figures.
 - Additional Formatting functions from the stoner Package.
+- Added a DoubleYAxis context manager for helping with double-y axis plots.
 
 ## v1.5.2 Release
 

README.md

@@ -11,14 +11,14 @@
 
 # Stoner Plots
 
-Stoner Plots is a fork of Science Plots
+Stoner Plots is a fork of Science Plots with additional features to make plotting of scientific plots easier.
 
 <img src="https://raw.githubusercontent.com/stonerlab/stonerplots/main/examples/figures/fig05a.png" width=640 alt="Presentation Style Image"/>
 
 ## Usage
 
-Before using the new styles you need to import stonerplots - but it's ok to just import e.g. the SavedFigure context
-manager:
+Before using the new styles you need to import stonerplots - but you will most likely also want to make use of
+one of the context managers - the `SavedFigure` class.::
 
     from stonerplots import SavedFigure
 
@@ -27,21 +27,18 @@ manager:
         plt.plot(x,y,label="Dataset")
         ...
 
-The SavedFigure context manager will handle the call to the matplotlib style context manager and will also save any
-figures opened within the context manager. If the filename for the figure has an embedded place holder for {ix}, then
-multiple figures can be saved without clobbering the filename.
+There are three main parts to this package::
 
-There is also an InsetPlot context manager that can help you get insets placed correctly so that axes
-labels don't escape over the edge of the surrounding figure.
+1. A set of matplotlib style sheets for making lots wih styles suitable for a variety of Physics related journals
+   and formats such as presentations and posters as well as reports and theses.
 
-    with SavedFigure("my_figure.pdf", style=["stoner","aps"]):
-        plt.figure()
-        plt.plot(x,y,label="Dataset")
-        ...
-        with InsetPlot(loc="lower right", width=0.25, height=0.25, padding=0.05) as inset:
-            inset.plot(x, model(x, 200), linestyle="--")
+1. A set of Python Content managers designed to help with the process of preparing production quality figures in
+  matplotlib.
+
+1. Soem defintitions of colours based on the Transport for London colour palette and inserted as named colours into
+   the matplotlib colour tables.
 
-See below for the full list of styles and context managers.
+The package is fully documented (see link below) and comes with a set of examples that also server as unit tests.
 
 ## Documentation
 
@@ -71,6 +68,7 @@ Documentation can be found on the [github pages for this repository](https://sto
 - aip2 - Switch to 2 column wide format for AIP journals
 - stoner-dark - Switch to a dark background a lighter plotting colours.
 - hi-res - Switches to 600dpi plotting (but using eps, pdf or svg is generally a better option)
+- med-res - like hi-res, but switches to 300dpi plotting.
 - presentation_sm - a style for making 1/2 width graphs.
 - presentation_dark - tweak the weight of elements for dark presnetations.
 - science-2col, science-3col - Science 2 and 3 column width figures
@@ -104,16 +102,44 @@ The package is designed to work by using python context managers to aid plotting
   the top-x-axis on one frame is the bottom of the next.
 - MultiPanel - a general; purpose miulti-panel plotting helper.
 - InsetPlot - create an inset set of axes.
+- DoubleYAxis - setup the righthand y axis for a second scale and optional colour the y-axes differently and merge
+  the legend into a single legend.
 
 This package draws heavily on [scienceplots](https://github.com/garrettj403/SciencePlots), so it seems only fair to cite the original work....
 
-    @article{StonerPlots,
-      author       = {John D. Garrett},
-      title        = {{garrettj403/SciencePlots}},
-      month        = sep,
-      year         = 2021,
-      publisher    = {Zenodo},
-      version      = {1.0.9},
-      doi          = {10.5281/zenodo.4106649},
-      url          = {http://doi.org/10.5281/zenodo.4106649}
-    }
+@software{john_garrett_2023_10206719,
+  author       = {John Garrett and
+                  Echedey Luis and
+                  H.-H. Peng and
+                  Tim Cera and
+                  gobinathj and
+                  Josh Borrow and
+                  Mehmet Keçeci and
+                  Splines and
+                  Suraj Iyer and
+                  Yuming Liu and
+                  cjw and
+                  Mikhail Gasanov},
+  title        = {garrettj403/SciencePlots: 2.1.1},
+  month        = nov,
+  year         = 2023,
+  publisher    = {Zenodo},
+  version      = {2.1.1},
+  doi          = {10.5281/zenodo.10206719},
+  url          = {https://doi.org/10.5281/zenodo.10206719},
+}
+
+The doi and BibTex reference for stonerplots is:
+
+https://doi.org/10.5281/zenodo.14026874
+
+@software{gavin_burnell_2024_14026874,
+  author       = {Gavin Burnell},
+  title        = {stonerlab/stonerplots},
+  month        = nov,
+  year         = 2024,
+  publisher    = {Zenodo},
+  version      = {v1.5.2},
+  doi          = {10.5281/zenodo.14026874},
+  url          = {https://doi.org/10.5281/zenodo.14026874},
+}

docs/source/colours.rst

@@ -1,34 +1,104 @@
 StonerPlot Colours
-==================
+===================
 
-The StonerPlots package default style ('stoner') includes a colour and line marker cycler. The colours used are
-taken from the Tansport for London colour palette (aka the Tube map) as they are a nice set of bold colours that
-show up well on white backgrounds.
+The StonerPlots package provides a default style ('stoner') that includes a colour and line marker cycler. The colours used are
+inspired by the **Transport for London (TfL)** colour palette (better known as the Tube map palette). This palette features
+a vibrant collection of bold colours, which are particularly effective for visualizations with white backgrounds.
 
-In addition, the package patches the matplotlib list of named colours so that you can use the colours directly -
-according to their tube/transport line. This maybe on makes sense to Brits!
+Additionally, the StonerPlots package extends the default list of named colours in matplotlib. This allows users to directly reference
+these colours by the names of the London Underground lines (e.g., 'bakerloo', 'central') in their visualizations. However, this naming
+may be most intuitive for users familiar with the London Underground system!
+
+**Why use the TfL palette?**
+- Visually appealing: The bold colours stand out against light and white backgrounds.
+- Consistency: Named options provide an easier way to stylize plots systematically.
+- Hierarchical shades: The palette includes predefined shades (e.g., 90%, 70%, etc.), offering flexibility while maintaining a unified look.
+
+---
 
 Tube Map Colours
-----------------
+-----------------
+The full set of Tube map colours is shown below. The colours correspond to the official line names.
 
 .. image:: figures/colours.png
+   :alt: Full tube map colour palette
+   :align: center
+   :width: 600px
+
+---
 
 Tube Map 90% Shade Colours
---------------------------
+---------------------------
+The 90% shade of each Tube line's colour offers a slightly darker tone while still preserving the colour identity.
+These shades are particularly effective for creating layered or hierarchical plots.
 
 .. image:: figures/colours90.png
+   :alt: 90% shaded tube map colours
+   :align: center
+   :width: 600px
+
+---
 
 Tube Map 70% Shade Colours
---------------------------
+---------------------------
+The 70% shades provide an intermediate level of opacity, useful for combining multiple elements on a plot while maintaining
+distinction.
 
 .. image:: figures/colours70.png
+   :alt: 70% shaded tube map colours
+   :align: center
+   :width: 600px
+
+---
 
 Tube Map 50% Shade Colours
---------------------------
+---------------------------
+The 50% shades offer further blending opportunities, creating a subtler appearance for secondary elements in plots.
 
 .. image:: figures/colours50.png
+   :alt: 50% shaded tube map colours
+   :align: center
+   :width: 600px
+
+---
 
 Tube Map 10% Shade Colours
---------------------------
+---------------------------
+The 10% shades, being faint versions of the original Tube map colours, can be used for plot backgrounds, grids, or
+less prominent plot elements.
 
 .. image:: figures/colours10.png
+   :alt: 10% shaded tube map colours
+   :align: center
+   :width: 600px
+
+---
+
+Using the StonerPlots Colour Palette
+------------------------------------
+The StonerPlots colour palette integrates seamlessly with matplotlib, allowing you to use colours based on their Tube map names.
+Here's an example of how the colour names could correspond to their respective London Underground lines:
+
++-------------------+---------------------+
+| Tube Line         | Colour (Hex Code)  |
++===================+=====================+
+| Bakerloo          | #B36305            |
+| Central           | #E32017            |
+| Circle            | #FFD300            |
+| District          | #00782A            |
+| Hammersmith & City| #F3A9BB            |
+| Jubilee           | #A0A5A9            |
+| Metropolitan      | #9B0056            |
+| Northern          | #000000            |
+| Piccadilly        | #003688            |
+| Victoria          | #0098D4            |
+| Waterloo & City   | #95CDBA            |
++-------------------+---------------------+
+
+For shades, consider appending `90`, `70`, etc., to form a hierarchy of shades for the respective lines.
+
+---
+
+## Notes
+- If you're unfamiliar with the TfL Tube map colours, they are based on London's underground transport line colours.
+  More details can be found [here on Transport for London's website](https://tfl.gov.uk).

docs/source/index.rst

@@ -1,7 +1,7 @@
 .. StonerPlots documentation master file, created by
-   sphinx-quickstart on Wed Mar 27 11:46:49 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+sphinx-quickstart on Wed Mar 27 11:46:49 2024.
+You can adapt this file completely to your liking, but it should at least
+contain the root `toctree` directive.
 
 Welcome to StonerPlots's documentation!
 =======================================
@@ -13,66 +13,79 @@ Welcome to StonerPlots's documentation!
 Introduction
 ------------
 
-StonerPlots is a package to help make publication quality matplotlib figures more easily. In particular,
-it is indended to create plots that match the style of common Physics journals, but equally can help
-keep matplotlib figures consistent for writing reports and theses.
+StonerPlots is a Python package designed to simplify the creation of publication-quality matplotlib figures. In particular, it is intended to produce plots that align with the style of common physics journals. StonerPlots also helps ensure consistency in matplotlib figures for reports, theses, and similar documentation.
 
-It originated as a fork of the scienceplots package by John D. Garrett
+The library originated as a fork of the `scienceplots` package by John D. Garrett.
 
 Quickstart
 ----------
 
 Installation
 ~~~~~~~~~~~~
 
-StonerPlots can be installed wither with pip or with conda::
+StonerPlots can be installed using either `pip` or `conda`:
 
-    pip install stonerplots
+```bash
+pip install stonerplots
+```
 
-Conda packages are uploaded to the Anaconda channel phygbu::
+Conda packages are available from the Anaconda channel `phygbu`:
 
-    conda install -c phygbu stonerplots
+```bash
+conda install -c phygbu stonerplots
+```
 
-It is packaged for python >= 3.10 and you need to have matplotlib installed as well (obviously!). The
-example code also uses numpy.
+StonerPlots requires **Python 3.10 or later** and depends on `matplotlib`, which will be installed automatically. However, most example code also makes use of `numpy`, so you may wish to ensure it is installed.
 
 Example
 ~~~~~~~
 
-The easiest way to get started is to use the SavedFigure context manager. This both applies the requested
-styles and also collects any new figures and saves them to disk.::
+The easiest way to get started is by using the `SavedFigure` context manager. This automatically applies the requested styles and collects any new figures, saving them to disk:
 
-    x = np.linspace(-np.pi,np.pi,181)
-    params = {"xlabel":r"Angle $^\circ$","ylabel":"Signal (V)"}
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+from stonerplots import SavedFigure
 
-    with SavedFigure(figures / "example-1.png"):
-        fig, ax = plt.subplots()
-        for i in range(1,6):
-            ax.plot(x*180/np.pi,(1/i)*np.sin(x*i+np.pi/i),
-                                    marker="", label=f"{i=}")
-        ax.legend(title="Curve")
-        ax.set(**params)
+# Generate example data
+x = np.linspace(-np.pi, np.pi, 181)
+fig_params = {"xlabel": r"Angle ($^\circ$)", "ylabel": "Signal (V)"}
 
-In this example, the new figure will be saved as example-1.png (auto-detecting the png format) in the path *figures*. and the
-default "stoner" stylesheet will be applied.
+# Save a styled figure
+with SavedFigure("figures/example-1.png"):  # Replace 'figures' with your desired output path
+    fig, ax = plt.subplots()
+    for i in range(1, 6):
+        ax.plot(x * 180 / np.pi, (1 / i) * np.sin(x * i + np.pi / i),
+                marker="", label=f"i = {i}")
+    ax.legend(title="Curve")
+    ax.set(**fig_params)
+```
+
+In this example, the `SavedFigure` context manager applies the default "stoner" stylesheet and saves the figure as `example-1.png`. The file will be saved in the specified output directory (`figures`), which must already exist. Ensure to adjust the path as needed for your use case.
 
 .. image:: figures/example-1.png
-  :alt: Example figure formatted with the 'stoner' style sheet.
+   :alt: Sample figure automatically styled using the 'stoner' style sheet.
+   :width: 600px
+   :align: center
 
 Sections
 ========
 
+Explore various aspects of StonerPlots through the following sections:
+
 .. toctree::
    :maxdepth: 2
 
-   User Guide <userguide>
-   Style Gallery <style-gallery>
-   Colours <colours>
-   API <api>
+   User Guide <userguide>       # Basic instructions for using StonerPlots
+   Style Gallery <style-gallery> # Examples of available map styles
+   Colours <colours>             # Full palette of colour options, including shaded variations
+   API <api>                     # Detailed API references
 
 Indices and tables
 ==================
 
+Explore further using the indices and search functionality provided below:
+
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`