documentation improvements

.gitignore

@@ -27,7 +27,7 @@ fastf1/tests/mpl-baseline-new/
 
 # documentation build directories
 docs/_build/
-docs/examples_gallery/
+docs/gen_modules/
 **/sg_execution_times.rst
 
 # all variations of cache directories

docs/changelog/index.rst

@@ -3,5 +3,5 @@ Release Notes
 
 Looking for :ref:`previous-release-notes`?
 
-.. include:: v3.3.x.rst
+.. include:: v3.4.x.rst
 

docs/changelog/previous.rst

@@ -8,6 +8,7 @@ Release Notes for Older Versions
 .. toctree::
   :maxdepth: 1
 
+  v3.3.x
   v3.2.x
   v3.1.x
   v3.0.x

docs/conf.py

@@ -152,13 +152,19 @@ def sphinx_gallery_setup(gallery_conf, fname):
 
 sphinx_gallery_conf = {
     'examples_dirs': '../examples',
-    'gallery_dirs': 'examples_gallery',
+    'gallery_dirs': 'gen_modules/examples_gallery',
     'download_all_examples': False,
     'remove_config_comments': True,
     'image_scrapers': ('matplotlib',  # default
                        plotly_sg_scraper),  # for plotly thumbnail
     'reset_modules': ('matplotlib', 'seaborn',  # defaults
                       sphinx_gallery_setup),  # custom setup
+    # directory where function/class granular galleries are stored
+    'backreferences_dir': 'gen_modules/backreferences',
+
+    # Modules for which function/class level galleries are created. In
+    # this case sphinx_gallery and numpy in a tuple of strings.
+    'doc_module': ('fastf1', ),
 }
 
 

docs/examples/basics.rst

@@ -336,5 +336,5 @@ So let's see what the fastest lap time was and who is on pole.
 
 
 Check out this example that shows how you can plot lap times:
-:ref:`sphx_glr_examples_gallery_plot_qualifying_results.py`
+:ref:`sphx_glr_gen_modules_examples_gallery_plot_qualifying_results.py`
 

docs/index.rst

@@ -25,7 +25,7 @@ tyre data, weather data, the event schedule and session results.
 
 
 To get a quick overview over how to use FastF1, check out
-:doc:`examples/index` or the :doc:`examples_gallery/index`.
+:doc:`examples/index` or the :doc:`gen_modules/examples_gallery/index`.
 
 Note that FastF1 handles big chunks of data (~50-100mb per session). To improve
 performance, data is per default cached locally. The default placement
@@ -141,7 +141,7 @@ Contents
    :caption: Contents:
 
    examples/index
-   examples_gallery/index
+   gen_modules/examples_gallery/index
    fastf1
    core
    events

docs/plotting.rst

@@ -1,9 +1,30 @@
 Plotting - :mod:`fastf1.plotting`
 =================================
 
+
+Overview
+--------
+
+
+Configuration and Setup
+^^^^^^^^^^^^^^^^^^^^^^^
+
 .. automodule:: fastf1.plotting
-  :members:
-    add_sorted_driver_legend,
+  :noindex:
+  :no-members:
+  :autosummary:
+  :autosummary-members:
+    setup_mpl
+
+
+Get Colors, Names and Abbreviations for Drivers or Teams
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: fastf1.plotting
+  :noindex:
+  :no-members:
+  :autosummary:
+  :autosummary-members:
     get_compound_color,
     get_driver_abbreviation,
     get_driver_abbreviations_by_team,
@@ -13,21 +34,63 @@ Plotting - :mod:`fastf1.plotting`
     get_driver_style,
     get_team_color,
     get_team_name,
-    get_team_name_by_driver,
-    setup_mpl,
-    driver_color,
-    team_color
-  :show-inheritance:
+    get_team_name_by_driver
+
+
+List all Names and Abbreviations for Drivers/Teams in a Session
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: fastf1.plotting
+  :noindex:
+  :no-members:
+  :autosummary:
+  :autosummary-members:
+    get_compound_mapping,
+    get_driver_color_mapping,
+    list_driver_abbreviations,
+    list_driver_names,
+    list_full_team_names,
+    list_short_team_names,
+    list_team_names
+
 
-Deprecated Attributes
----------------------
+Plot Styling
+^^^^^^^^^^^^
+
+.. automodule:: fastf1.plotting
+  :noindex:
+  :no-members:
+  :autosummary:
+  :autosummary-members:
+    add_sorted_driver_legend
 
-The following module-level attributes are deprecated since version 3.3.0 and
+
+Deprecated Functionality
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following module-level attributes are deprecated since version 3.4.0 and
 will be removed in a future release.
 
+
+.. automodule:: fastf1.plotting
+  :noindex:
+  :no-members:
+  :autosummary:
+  :autosummary-members:
+    driver_color,
+    lapnumber_axis,
+    team_color,
+    COMPOUND_COLORS,
+    DRIVER_TRANSLATE,
+    DRIVER_COLORS,
+    TEAM_COLORS,
+    TEAM_TRANSLATE,
+    COLOR_PALETTE
+
+
+
+Plotting API Reference
+----------------------
+
 .. automodule:: fastf1.plotting
-  :no-index:
   :members:
-  :exclude-members:
-    get_compound_color
-  :show-inheritance:

fastf1/plotting/__init__.py

@@ -41,6 +41,43 @@
 )
 
 
+__all__ = [
+    # imported, current
+    'add_sorted_driver_legend',
+    'get_compound_color',
+    'get_compound_mapping',
+    'get_driver_abbreviation',
+    'get_driver_abbreviations_by_team',
+    'get_driver_color',
+    'get_driver_color_mapping',
+    'get_driver_name',
+    'get_driver_names_by_team',
+    'get_driver_style',
+    'get_team_color',
+    'get_team_name',
+    'get_team_name_by_driver',
+    'list_driver_abbreviations',
+    'list_driver_names',
+    'list_full_team_names',
+    'list_short_team_names',
+    'list_team_names',
+    'setup_mpl',
+
+    # imported, legacy
+    'driver_color',
+    'lapnumber_axis',
+    'team_color',
+
+    # legacy
+    'COMPOUND_COLORS',
+    'DRIVER_COLORS',
+    'DRIVER_TRANSLATE',
+    'TEAM_COLORS',
+    'TEAM_TRANSLATE',
+    'COLOR_PALETTE'
+]
+
+
 def __getattr__(name):
     if name in ('COMPOUND_COLORS', 'DRIVER_TRANSLATE', 'DRIVER_COLORS',
                 'TEAM_COLORS', 'TEAM_TRANSLATE', 'COLOR_PALETTE'):
@@ -61,10 +98,10 @@ def __getattr__(name):
 Mapping of tyre compound names to compound colors (hex color codes).
 (current season only)
 
-.. deprecated:: 3.3.0
+.. deprecated:: 3.4.0
     The ``COMPOUND_COLORS`` dictionary is deprecated and will be removed in a
     future version. Use :func:`~fastf1.plotting.get_compound_color` or
-    :func:`~fastf1.plotting.get_compound_color_mapping` instead.
+    :func:`~fastf1.plotting.get_compound_mapping` instead.
 """
 
 
@@ -77,7 +114,7 @@ def __getattr__(name):
     This dictionary will no longer be updated to include new drivers. Use
     the new API instead.
 
-.. deprecated:: 3.3.0
+.. deprecated:: 3.4.0
     The ``DRIVER_COLORS`` dictionary is deprecated and will ber removed in a
     future version. Use :func:`~fastf1.plotting.get_driver_color` or
     :func:`~fastf1.plotting.get_driver_color_mapping` instead.
@@ -94,7 +131,7 @@ def __getattr__(name):
     the new API instead.
 
 
-.. deprecated:: 3.3.0
+.. deprecated:: 3.4.0
     The ``DRIVER_TRANSLATE`` dictionary is deprecated and will be removed in a
     future version. Use :func:`~fastf1.plotting.get_driver_name` instead.
 """
@@ -110,7 +147,7 @@ def __getattr__(name):
 Mapping of team names to team colors (hex color codes).
 (current season only)
 
-.. deprecated:: 3.3.0
+.. deprecated:: 3.4.0
     The ``TEAM_COLORS`` dictionary is deprecated and will be removed in a
     future version. Use :func:`~fastf1.plotting.get_team_color` instead.
 """
@@ -120,7 +157,7 @@ def __getattr__(name):
 """
 Mapping of team names to theirs respective abbreviations.
 
-.. deprecated:: 3.3.0
+.. deprecated:: 3.4.0
     The ``TEAM_TRANSLATE`` dictionary is deprecated and will be removed in a
     future version. Use :func:`~fastf1.plotting.get_team_name` instead.
 """
@@ -130,7 +167,7 @@ def __getattr__(name):
 """
 The default color palette for matplotlib plot lines in fastf1's color scheme.
 
-.. deprecated:: 3.3.0
+.. deprecated:: 3.4.0
     The ``COLOR_PALETTE`` list is deprecated and will be removed in a
     future version with no replacement.
 """

fastf1/plotting/_interface.py

@@ -442,9 +442,6 @@ def get_driver_style(
         >>> get_driver_style('STR', style=my_styles, session=session)
         {'linestyle': 'dotted', 'color': '#FF0060', 'other_arg': 10}
 
-    .. seealso::
-        :ref:`sphx_glr_examples_gallery_plot_driver_styling.py`
-
     Args:
         identifier: driver abbreviation or recognizable part of the driver name
         style: list of matplotlib plot arguments that should be used for
@@ -457,6 +454,10 @@ def get_driver_style(
 
     Returns: a dictionary of plot style arguments that can be directly passed
         to a matplotlib plot function using the ``**`` expansion operator
+
+
+    .. minigallery:: fastf1.plotting.get_driver_style
+        :add-heading:
     """
     if session is None:
         raise ValueError('`session` must not be None')
@@ -641,12 +642,14 @@ def add_sorted_driver_legend(ax: matplotlib.axes.Axes, *, session: Session):
     There is no particular need to use this function except to make the
     legend more visually pleasing.
 
-    .. seealso::
-        :ref:`sphx_glr_examples_gallery_plot_driver_styling.py`
-
     Args:
         ax: An instance of a Matplotlib ``Axes`` object
         session: the session for which the data should be obtained
+
+
+    .. minigallery:: fastf1.plotting.add_sorted_driver_legend
+        :add-heading:
+
     """
     if session is None:
         raise ValueError('`session` must not be None')

fastf1/plotting/_plotting.py

@@ -102,7 +102,7 @@ def driver_color(identifier: str) -> str:
     """
     Get a driver's color from a driver name or abbreviation.
 
-    .. deprecated:: 3.3.0
+    .. deprecated:: 3.4.0
         This function is deprecated and will be removed in a future version.
         Use :func:`~fastf1.plotting.get_driver_color` instead.
 
@@ -147,7 +147,7 @@ def team_color(identifier: str) -> str:
     """
     Get a team's color from a team name or abbreviation.
 
-    .. deprecated:: 3.3.0
+    .. deprecated:: 3.4.0
         This function is deprecated and will be removed in a future version.
         Use :func:`~fastf1.plotting.get_team_color` instead.
 
@@ -300,7 +300,7 @@ def lapnumber_axis(ax, axis='xaxis'):
     """
     Set axis to integer ticks only.
 
-    .. deprecated:: 3.3.0
+    .. deprecated:: 3.4.0
         The function ``lapnumber_axis`` is deprecated and will ber removed in a
         future version without replacement.