From 19a9578a5aac25bebc81d9c92d98d236d83df74f Mon Sep 17 00:00:00 2001 From: theOehrly <23384863+theOehrly@users.noreply.github.com> Date: Tue, 9 Apr 2024 22:40:28 +0200 Subject: [PATCH] documentation improvements --- .gitignore | 2 +- docs/changelog/index.rst | 2 +- docs/changelog/previous.rst | 1 + docs/conf.py | 8 ++- docs/examples/basics.rst | 2 +- docs/index.rst | 4 +- docs/plotting.rst | 91 +++++++++++++++++++++++++++++------ fastf1/plotting/__init__.py | 51 +++++++++++++++++--- fastf1/plotting/_interface.py | 15 +++--- fastf1/plotting/_plotting.py | 6 +-- 10 files changed, 146 insertions(+), 36 deletions(-) diff --git a/.gitignore b/.gitignore index 9cb05c714..98fc55832 100644 --- a/.gitignore +++ b/.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 diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst index e5eb155ea..bce493ab2 100644 --- a/docs/changelog/index.rst +++ b/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 diff --git a/docs/changelog/previous.rst b/docs/changelog/previous.rst index 6e02c04a2..cfe3d24a9 100644 --- a/docs/changelog/previous.rst +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index a8003be14..6ca9f6d1d 100644 --- a/docs/conf.py +++ b/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', ), } diff --git a/docs/examples/basics.rst b/docs/examples/basics.rst index 9a8260c8e..6c91086de 100644 --- a/docs/examples/basics.rst +++ b/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` diff --git a/docs/index.rst b/docs/index.rst index a1b3ce874..10a833a6c 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/plotting.rst b/docs/plotting.rst index 7383b5b56..cb2004e90 100644 --- a/docs/plotting.rst +++ b/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: diff --git a/fastf1/plotting/__init__.py b/fastf1/plotting/__init__.py index 1009653b6..a0b82320d 100644 --- a/fastf1/plotting/__init__.py +++ b/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. """ diff --git a/fastf1/plotting/_interface.py b/fastf1/plotting/_interface.py index fa606ae80..5bdf5cbba 100644 --- a/fastf1/plotting/_interface.py +++ b/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') diff --git a/fastf1/plotting/_plotting.py b/fastf1/plotting/_plotting.py index e92b38837..0a5f6a2dd 100644 --- a/fastf1/plotting/_plotting.py +++ b/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.