Enhance tueplots' documentation (#162)

* Update the mentioning of available styles

* Write module-level docstrings for axes.py and __init__.py

* Module-level docstrings for all modules

* Add usage examples to most module-level docstrings

* Demo figsizes & fontsizes together because they go together

* Delete an unused sphinx extension

* Remove the doctests from tox

* Remove latex requirements from the doctests

* Don't use tex in __init__ docstring

Author: pnkraemer

docs/source/conf.py

@@ -19,6 +19,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "matplotlib.sphinxext.plot_directive",
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.todo",

docs/source/index.rst

@@ -6,10 +6,8 @@
 TUEplots reference documentation
 ================================
 
-TUEplots is a light-weight matplotlib extension
-that adapts your figure sizes to formats more suitable for scientific publications.
-It produces configurations that are compatible with matplotlib's `rcParams`,
-and provides fonts, figure sizes, font sizes, color schemes, and more, for a number of publication formats.
+TUEplots is a light-weight matplotlib extension that adapts your figure sizes to formats more suitable for scientific publications.
+It produces configurations that are compatible with matplotlib's `rcParams`, and provides fonts, figure sizes, font sizes, color schemes, and more, for a number of publication formats.
 
 
 Supported Venues
@@ -23,6 +21,12 @@ The following venues are currently supported by TUEplots out of the box as pre-c
 - International Conference on Machine Learning (ICML)
 - Conference on Uncertainty in Artificial Intelligence (UAI)
 - Journal of Machine Learning Research (JMLR)
+- Transactions of Machine Learning Research (TMLR)
+- Conference on Computer Vision and Pattern Recognition (CVPR)
+- Association for the Advancement of Artificial Intelligence (AAAI)
+- European Conference on Computer Vision (ECCV)
+- International Conference on Probabilistic Numerics (ProbNum)
+
 
 For further details on the available bundles, check out the `tueplots.bundles API documentation <docs_api/tueplots.bundles.rst>`_.
 

tox.ini

@@ -10,11 +10,13 @@ deps =
     pytest-cases
     matplotlib
 commands =
+    ; The doctests in the src are not run here because the doc-build executes them
     pytest {posargs}
     python -m doctest docs/source/getting_started/application_icml2022.md
     python -m doctest docs/source/getting_started/usage_example.md
 
 
+
 [testenv:format-and-lint]
 description = Lint the code with black, isort, and pylint
 deps =

tueplots/__init__.py

@@ -1,3 +1,29 @@
-"""TUEplots."""
+"""``tueplots`` package.
+
+``tueplots`` is a Python package that helps you create plots that match the styles and guidelines of different conferences and journals.
+Each module in TUEplots provides specific settings like fonts, figure sizes, axes behavior, and bundled configurations for specific conferences.
+
+Examples
+--------
+
+.. plot::
+    :include-source: True
+
+    >>> import matplotlib.pyplot as plt
+    >>> from tueplots import bundles
+    >>>
+    >>> # Select a style bundle
+    >>> style = bundles.icml2024(usetex=False)
+    >>>
+    >>> # Apply the style to matplotlib
+    >>> plt.rcParams.update(style)
+    >>>
+    >>> # Create a plot
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 1, 2], [2, 1, 3])
+    >>> ax.set_xlabel("$x$ label")
+    >>> ax.set_ylabel("$y$ label")
+    >>> plt.show()
+"""
 
 from ._version import version as __version__

tueplots/axes.py

@@ -1,4 +1,30 @@
-"""Axes behaviour."""
+"""Customise matplotlib axes (:mod:`tueplots.axes`).
+
+Provides functions to adjust axis appearance, including grid lines,
+spines, ticks, and legends.
+
+Examples
+--------
+
+.. plot::
+    :include-source: True
+
+    >>> import matplotlib.pyplot as plt
+    >>> from tueplots import axes
+    >>>
+    >>> # Select a style bundle
+    >>> style = axes.spines(right=False, top=False)
+    >>>
+    >>> # Apply the style to matplotlib
+    >>> plt.rcParams.update(style)
+    >>>
+    >>> # Create a plot
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 1, 2], [2, 1, 3])
+    >>> ax.set_xlabel("$x$ label")
+    >>> ax.set_ylabel("$y$ label")
+    >>> plt.show()
+"""
 
 
 def lines(

tueplots/bundles.py

@@ -1,4 +1,31 @@
-"""Bundled configurations."""
+"""Predefined style settings (:mod:`tueplots.bundles`).
+
+Includes ready-to-use style configurations for major conferences
+and journals. Bundles figure sizes, font sizes, fonts, and so on.
+
+Examples
+--------
+
+.. plot::
+    :include-source: True
+
+    >>> import matplotlib.pyplot as plt
+    >>> from tueplots import bundles
+    >>>
+    >>> # Select a style bundle
+    >>> style = bundles.neurips2021(usetex=False)
+    >>>
+    >>> # Apply the style to matplotlib
+    >>> plt.rcParams.update(style)
+    >>>
+    >>> # Create a plot
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 1, 2], [2, 1, 3])
+    >>> ax.set_xlabel("$x$ label")
+    >>> ax.set_ylabel("$y$ label")
+    >>> plt.show()
+
+"""
 
 from tueplots import axes, cycler, figsizes, fonts, fontsizes
 from tueplots.constants.color import palettes, rgb

tueplots/constants/__init__.py

@@ -0,0 +1,5 @@
+"""Collection of predefined constants (:mod:`tueplots.constants`).
+
+Provides standardised values for colours, line styles, markers,
+and figure sizes.
+"""

tueplots/constants/color/__init__.py

@@ -0,0 +1,4 @@
+"""Colour definitions and tools (:mod:`tueplots.constants.color`).
+
+Includes named colours and utilities for working with colour schemes.
+"""

tueplots/constants/color/palettes.py

@@ -1,4 +1,7 @@
-"""Color palettes."""
+"""Predefined colour palettes (:mod:`tueplots.constants.color.palettes`).
+
+Offers curated colour sets for consistent and visually appealing plots.
+"""
 
 import numpy as np
 

tueplots/constants/color/rgb.py

@@ -1,4 +1,7 @@
-"""RGB color constants."""
+"""Standard colour definitions (:mod:`tueplots.constants.colours`).
+
+Lists predefined colours for consistency in visualisations.
+"""
 
 import numpy as np
 

tueplots/constants/markers.py

@@ -1,4 +1,7 @@
-"""Marker collections."""
+"""Marker shape presets (:mod:`tueplots.constants.markers`).
+
+Defines commonly used marker styles for plots.
+"""
 
 import numpy as _np
 

tueplots/cycler.py

@@ -1,4 +1,8 @@
-"""Wrapper for matplotlib cycler."""
+"""Colour and style cycling (:mod:`tueplots.cycler`).
+
+Defines custom cyclers for colours, markers, and line styles to
+keep plots visually distinct.
+"""
 
 from matplotlib import cycler as mpl_cycler
 

tueplots/figsizes.py

@@ -1,4 +1,32 @@
-"""Figure size settings."""
+"""Figure size presets (:mod:`tueplots.figsizes`).
+
+Provides standard figure dimensions for publications, ensuring
+proper scaling in papers.
+
+Examples
+--------
+
+.. plot::
+    :include-source: True
+
+    >>> import matplotlib.pyplot as plt
+    >>> from tueplots import figsizes, fontsizes
+    >>>
+    >>> # Select a style bundle: fontsize + figsize
+    >>> style = figsizes.aistats2025_half() | fontsizes.aistats2025()
+    >>>
+    >>> # Apply the style to matplotlib
+    >>> plt.rcParams.update(style)
+    >>>
+    >>> # Create a plot
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 1, 2], [2, 1, 3])
+    >>> ax.set_xlabel("$x$ label")
+    >>> ax.set_ylabel("$y$ label")
+    >>> plt.show()
+
+
+"""
 
 # Some useful constants
 _GOLDEN_RATIO = (5.0**0.5 - 1.0) / 2.0

tueplots/fonts.py

@@ -1,4 +1,32 @@
-"""Font settings for conference papers and journals."""
+"""Font settings for plots (:mod:`tueplots.fonts`).
+
+Configures fonts to match LaTeX documents.
+
+
+Examples
+--------
+
+.. plot::
+    :include-source: True
+
+    >>> import matplotlib.pyplot as plt
+    >>> from tueplots import fonts
+    >>>
+    >>> # Select a style bundle
+    >>> style = fonts.neurips2021()
+    >>>
+    >>> # Apply the style to matplotlib
+    >>> plt.rcParams.update(style)
+    >>>
+    >>> # Create a plot
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 1, 2], [2, 1, 3])
+    >>> ax.set_xlabel("$x$ label")
+    >>> ax.set_ylabel("$y$ label")
+    >>> plt.show()
+
+
+"""
 
 
 def neurips2021(*, family="serif"):

tueplots/fontsizes.py

@@ -1,4 +1,33 @@
-"""Fontsize settings."""
+"""Adapt font sizes (:mod:`tueplots.fontsizes`).
+
+Sets appropriate font sizes for labels, legends, and titles
+in publication-ready figures.
+
+
+Examples
+--------
+
+.. plot::
+    :include-source: True
+
+    >>> import matplotlib.pyplot as plt
+    >>> from tueplots import fontsizes, figsizes
+    >>>
+    >>> # Select a style bundle: fontsize + figsize
+    >>> style = fontsizes.cvpr2024() | figsizes.cvpr2022_half()
+    >>>
+    >>> # Apply the style to matplotlib
+    >>> plt.rcParams.update(style)
+    >>>
+    >>> # Create a plot
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 1, 2], [2, 1, 3])
+    >>> ax.set_xlabel("$x$ label")
+    >>> ax.set_ylabel("$y$ label")
+    >>> plt.show()
+
+
+"""
 
 
 def icml2022(*, default_smaller=1):

tueplots/markers.py

@@ -1,4 +1,32 @@
-"""Marker styles."""
+"""Marker styles and sizes (:mod:`tueplots.markers`).
+
+Provides predefined marker shapes and sizes for scatter plots
+and line charts.
+
+Examples
+--------
+
+.. plot::
+    :include-source: True
+
+    >>> import matplotlib.pyplot as plt
+    >>> from tueplots import markers
+    >>>
+    >>> # Select a style bundle
+    >>> style = markers.with_edge()
+    >>>
+    >>> # Apply the style to matplotlib
+    >>> plt.rcParams.update(style)
+    >>>
+    >>> # Create a plot
+    >>> fig, ax = plt.subplots()
+    >>> ax.plot([0, 1, 2], [2, 1, 3], "o-")
+    >>> ax.set_xlabel("$x$ label")
+    >>> ax.set_ylabel("$y$ label")
+    >>> plt.show()
+
+
+"""
 
 
 def with_edge(*, edgecolor="black", edgewidth=0.5):