diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml index 2bef7ab95a56..5c9afed3c02b 100644 --- a/.github/FUNDING.yml +++ b/.github/FUNDING.yml @@ -1,3 +1,3 @@ # These are supported funding model platforms -github: [numfocus] +github: [matplotlib, numfocus] custom: https://numfocus.org/donate-to-matplotlib diff --git a/doc/_static/mpl.css b/doc/_static/mpl.css index 88c620d559e8..b5ac4b6ddd3a 100644 --- a/doc/_static/mpl.css +++ b/doc/_static/mpl.css @@ -212,3 +212,11 @@ table.property-table th, table.property-table td { padding: 4px 10px; } + +.donate-button { + margin: 1em 0; +} + +.sphinxsidebarwrapper { + margin: 0 1em; +} diff --git a/doc/_templates/cheatsheet_sidebar.html b/doc/_templates/cheatsheet_sidebar.html new file mode 100644 index 000000000000..615c2bc4cd04 --- /dev/null +++ b/doc/_templates/cheatsheet_sidebar.html @@ -0,0 +1,9 @@ + +
+

Matplotlib cheatsheets

+ + Matplotlib cheatsheets + +
diff --git a/doc/_templates/donate_sidebar.html b/doc/_templates/donate_sidebar.html index fc7310b70088..02d5ff6fc46c 100644 --- a/doc/_templates/donate_sidebar.html +++ b/doc/_templates/donate_sidebar.html @@ -1,6 +1,8 @@ - - -
-

Matplotlib cheatsheets

- - Matplotlib cheatsheets - -
diff --git a/doc/conf.py b/doc/conf.py index 00f7ed7c5ea2..77b879d6f371 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -71,12 +71,15 @@ 'sphinxext.skip_deprecated', 'sphinxext.redirect_from', 'sphinx_copybutton', + 'sphinx_panels', ] exclude_patterns = [ 'api/prev_api_changes/api_changes_*/*', ] +panels_add_bootstrap_css = False + def _check_dependencies(): names = { @@ -312,8 +315,9 @@ def _check_dependencies(): "url": "https://twitter.com/matplotlib/", "icon": "fab fa-twitter-square", }, - ], + "show_prev_next": False, + "navbar_center": ["mpl_nav_bar.html"], } include_analytics = False if include_analytics: @@ -341,8 +345,10 @@ def _check_dependencies(): # Custom sidebar templates, maps page names to templates. html_sidebars = { "index": [ + 'search-field.html', # 'sidebar_announcement.html', "sidebar_versions.html", + "cheatsheet_sidebar.html", "donate_sidebar.html", ], # '**': ['localtoc.html', 'pagesource.html'] diff --git a/doc/contents.rst b/doc/contents.rst index 37fd17172ce2..f9d10936c7fc 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -1,4 +1,4 @@ - +.. _complete_sitemap: Contents ======== @@ -15,13 +15,10 @@ Contents :maxdepth: 2 users/installing.rst - plot_types/index.rst - gallery/index.rst - tutorials/index.rst - api/index.rst users/index.rst + users/backmatter.rst devel/index.rst - Third-party packages + users/release_notes.rst .. only:: html diff --git a/doc/faq/index.rst b/doc/faq/index.rst index def68fc84c71..bb477de21f0e 100644 --- a/doc/faq/index.rst +++ b/doc/faq/index.rst @@ -1,8 +1,8 @@ .. _faq-index: -################## -The Matplotlib FAQ -################## +###### +How-to +###### .. only:: html diff --git a/doc/index.rst b/doc/index.rst index 3b18def1db3c..9d77ba0a4d39 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,41 +4,109 @@ .. module:: matplotlib -Matplotlib documentation ------------------------- -Release: |release| +Matplotlib |release| documentation +---------------------------------- Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations in Python. -Learn -===== - -- :doc:`Quick-start Guide ` -- Basic :doc:`Plot Types ` and :doc:`Example Gallery ` -- `Introductory Tutorials <../tutorials/index.html#introductory>`_ -- :doc:`External Learning Resources ` - -Reference -========= +Installation +============ -- :doc:`API Reference ` +.. panels:: + :card: + install-card + :column: col-lg-6 col-md-6 col-sm-12 col-xs-12 p-3 - - :doc:`pyplot API `: top-level interface to create - Figures (`.pyplot.figure`) and Subplots (`.pyplot.subplots`, - `.pyplot.subplot_mosaic`) - - :doc:`Axes API ` for *most* plotting methods - - :doc:`Figure API ` for figure-level methods + Installing using `conda `__ + ^^^^^^^^^^^^^^^^^^^^^^ -How-tos -======= -- :doc:`Installation Guide ` -- :doc:`Contributing to Matplotlib ` -- :doc:`Matplotlib FAQ ` -Understand how Matplotlib works -=============================== + .. code-block:: bash -- Many of the :doc:`Tutorials ` have explanatory material + conda install matplotlib + + --- + + Installing using `pip `__ + ^^^^^^^^^^^^^^^^^^^^ + + + .. code-block:: bash + + pip install matplotlib + + +Further details are available in the :doc:`Installation Guide `. + + +Learning resources +================== + + +.. panels:: + + Tutorials + ^^^^^^^^^ + + - :doc:`Quick-start Guide ` + - :doc:`Plot Types ` + - `Introductory Tutorials <../tutorials/index.html#introductory>`_ + - :doc:`External Learning Resources ` + + --- + + How-tos + ^^^^^^^ + - :doc:`Example Gallery ` + - :doc:`Matplotlib FAQ ` + + --- + + Understand how Matplotlib works + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - The :ref:`users-guide-explain` section of the :doc:`Users guide ` + - Many of the :ref:`Intermediate ` and + :ref:`Advanced ` Tutorials + have explanatory material + + --- + + Reference + ^^^^^^^^^ + + - :doc:`API Reference ` + - :doc:`Axes API ` for *most* plotting methods + - :doc:`Figure API ` for figure-level methods + - Top-level interfaces to create: + + - Figures (`.pyplot.figure`) + - Subplots (`.pyplot.subplots`, `.pyplot.subplot_mosaic`) + + + +Third-party packages +-------------------- + +There are many `Third-party packages +`_ built on top of and extending +Matplotlib. + + +Contributing +------------ + +Matplotlib is a community project maitained for and by its users. There are many ways +you can help! + +- Help other users `on discourse `__ +- report a bug or request a feature `on GitHub `__ +- or improve the :ref:`documentation and code ` + + +Site map +-------- + +The :ref:`complete contents of the docs `. diff --git a/doc/users/backmatter.rst b/doc/users/backmatter.rst new file mode 100644 index 000000000000..8d9fc0407d6f --- /dev/null +++ b/doc/users/backmatter.rst @@ -0,0 +1,11 @@ + +Project Information +------------------- + +.. toctree:: + :maxdepth: 1 + + license.rst + ../citing.rst + credits.rst + history.rst diff --git a/doc/users/explain.rst b/doc/users/explain.rst new file mode 100644 index 000000000000..d9d7a8474dbb --- /dev/null +++ b/doc/users/explain.rst @@ -0,0 +1,10 @@ +.. _users-guide-explain: + +Explanations +------------ + +.. toctree:: + :maxdepth: 1 + + interactive.rst + fonts.rst diff --git a/doc/users/fonts.rst b/doc/users/fonts.rst index e385c98284c0..1b9861df7414 100644 --- a/doc/users/fonts.rst +++ b/doc/users/fonts.rst @@ -1,16 +1,16 @@ -Fonts in Matplotlib Text Engine +Fonts in Matplotlib text engine =============================== Matplotlib needs fonts to work with its text engine, some of which are shipped alongside the installation. However, users can configure the default fonts, or -even provide their own custom fonts! For more details, see :doc:`Customizing +even provide their own custom fonts! For more details, see :doc:`Customizing text properties `. However, Matplotlib also provides an option to offload text rendering to a TeX engine (``usetex=True``), see :doc:`Text rendering with LaTeX `. -Font Specifications +Font specifications ------------------- Fonts have a long and sometimes incompatible history in computing, leading to different platforms supporting different types of fonts. In practice, there are @@ -40,7 +40,7 @@ fonts', more about which is explained later in the guide): NOTE: Adobe will disable support for authoring with Type 1 fonts in January 2023. `Read more here. `_ -Special Mentions +Special mentions ^^^^^^^^^^^^^^^^ Other font specifications which Matplotlib supports: diff --git a/doc/users/index.rst b/doc/users/index.rst index c4ec864df787..32d70d3537fe 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -1,23 +1,24 @@ .. _users-guide-index: -############ -User's guide -############ +########### +Usage Guide +########### .. only:: html :Release: |version| :Date: |today| + + + .. toctree:: - :maxdepth: 2 - - interactive.rst - fonts.rst - release_notes.rst - license.rst - ../citing.rst - ../resources/index.rst - ../faq/index.rst - credits.rst - history.rst + :maxdepth: 2 + + ../plot_types/index.rst + ../tutorials/index.rst + ../gallery/index.rst + explain.rst + ../faq/index.rst + ../api/index.rst + ../resources/index.rst diff --git a/examples/user_interfaces/test.bmp b/examples/user_interfaces/test.bmp new file mode 100644 index 000000000000..ae58370451a8 Binary files /dev/null and b/examples/user_interfaces/test.bmp differ diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt index 2cfba0dbad07..8be10d4d107c 100644 --- a/requirements/doc/doc-requirements.txt +++ b/requirements/doc/doc-requirements.txt @@ -12,12 +12,13 @@ colorspacious ipython ipywidgets numpydoc>=0.8 -pydata-sphinx-theme>=0.5.0 +pydata-sphinx-theme>=0.6.0 sphinxcontrib-svg2pdfconverter>=1.1.0 -# sphinx-gallery>=0.7 -# b41e328 is PR 808 which adds the image_srcset directive. When this is +# sphinx-gallery>=0.7 +# b41e328 is PR 808 which adds the image_srcset directive. When this is # released with sphinx gallery, we can change to the last release w/o this feature: # sphinx-gallery>0.90 git+git://github.com/sphinx-gallery/sphinx-gallery@b41e328#egg=sphinx-gallery sphinx-copybutton +sphinx-panels scipy