diff --git a/doc/conf.py b/doc/conf.py index 5375dba8f0ab..d5e946273b84 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -311,7 +311,7 @@ def gallery_image_warning_filter(record): source_encoding = "utf-8" # The toplevel toctree document (renamed to root_doc in Sphinx 4.0) -root_doc = master_doc = 'users/index' +root_doc = master_doc = 'index' # General substitutions. try: diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 3ad72d38fe4d..1146df77adf2 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -9,13 +9,16 @@ ways to contribute: optimizing and refactoring code, detailing unclear documentation and writing new examples, reporting and fixing bugs and requesting and implementing new features, helping the community... +New contributors +================ + .. card:: .. grid:: 1 1 2 2 + :class-row: sd-align-minor-center .. grid-item:: :class: sd-fs-5 - :child-align: spaced :octicon:`info;1em;sd-text-info` :ref:`Where should I start? ` @@ -67,12 +70,15 @@ For code, documentation, or triage, please follow the corresponding .. _development_environment: -Development workflow -==================== +Development environment +======================= .. grid:: 1 1 2 2 - .. grid-item-card:: Install + .. grid-item-card:: + + **Install** + ^^^ .. toctree:: :maxdepth: 2 @@ -85,7 +91,10 @@ Development workflow dependencies - .. grid-item-card:: Workflow + .. grid-item-card:: + + **Workflow** + ^^^^ .. toctree:: :maxdepth: 2 @@ -96,13 +105,17 @@ Development workflow .. _contribution_guideline: -Contribution guides -=================== +Policies and guidelines +======================= .. grid:: 1 1 2 2 :class-row: sf-fs-1 + :gutter: 2 + + .. grid-item-card:: - .. grid-item-card:: Code + **Code** + ^^^ | :ref:`coding_guidelines` @@ -112,7 +125,10 @@ Contribution guides coding_guide testing - .. grid-item-card:: Documentation + .. grid-item-card:: + + **Documentation** + ^^^ .. toctree:: :maxdepth: 1 @@ -120,13 +136,19 @@ Contribution guides document style_guide - .. grid-item-card:: Triage + .. grid-item-card:: + + **Triage** + ^^^ | :ref:`bug_triaging` | :ref:`triage_team` | :ref:`triage_workflow` - .. grid-item-card:: Maintenance + .. grid-item-card:: + + **Maintenance** + ^^^ .. toctree:: :maxdepth: 1 diff --git a/doc/index.rst b/doc/index.rst index 4e593f0688dc..8193c94aede9 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,5 +1,3 @@ -:orphan: - .. title:: Matplotlib documentation .. module:: matplotlib @@ -9,100 +7,169 @@ Matplotlib |release| documentation ################################## + Matplotlib is a comprehensive library for creating static, animated, -and interactive visualizations in Python. +and interactive visualizations. -************ -Installation -************ +Install +======= -.. grid:: 1 1 2 2 +.. tab-set:: + :class: sd-width-content-min - .. grid-item:: - - Install using `pip `__: + .. tab-item:: pip .. code-block:: bash pip install matplotlib - .. grid-item:: - - Install using `conda `__: + .. tab-item:: conda .. code-block:: bash conda install -c conda-forge matplotlib -Further details are available in the :doc:`Installation Guide `. + .. tab-item:: other + .. toctree:: + :maxdepth: 2 -****************** -Learning resources -****************** + users/installing/index + +For more detailed instructions, see the +:doc:`installation guide `. + +Learn +===== .. grid:: 1 1 2 2 .. grid-item-card:: :padding: 2 + :columns: 6 - Tutorials + **How to use Matplotlib?** ^^^ + .. toctree:: + :maxdepth: 1 - - :ref:`Quick-start guide ` - - :doc:`Plot types ` - - :ref:`users-guide-using` - - :doc:`External learning resources ` + users/explain/quick_start + User guide + tutorials/index.rst + users/faq/index.rst .. grid-item-card:: :padding: 2 + :columns: 6 - How-tos + **What can Matplotlib do?** ^^^ + .. toctree:: + :maxdepth: 1 + + plot_types/index.rst + gallery/index.rst - - :doc:`Example gallery ` - - :doc:`Matplotlib FAQ ` .. grid-item-card:: :padding: 2 + :columns: 12 - Understand how Matplotlib works + **Reference** ^^^ - - :ref:`users-guide-explain` in the :doc:`Users guide - ` has a number of advanced topics. + .. grid:: 1 1 2 2 + :class-row: sd-align-minor-center - .. grid-item-card:: - :padding: 2 + .. grid-item:: - Reference - ^^^ + .. toctree:: + :maxdepth: 1 - - :doc:`API Reference ` - - :doc:`Axes API ` for most plotting methods - - :doc:`Figure API ` for figure-level methods - - Top-level interfaces to create: + API reference + Figure methods + Plotting methods - - Figures (`.pyplot.figure`) - - Subplots (`.pyplot.subplots`, `.pyplot.subplot_mosaic`) + .. grid-item:: -******************** -Third-party packages -******************** + Top-level interfaces to create: -There are many `Third-party packages -`_ built on top of and extending -Matplotlib. + - figures: `.pyplot.figure` + - subplots: `.pyplot.subplots`, `.pyplot.subplot_mosaic` +Community +========= + +.. grid:: 1 1 2 2 + :class-row: sd-align-minor-center + + .. grid-item:: + + .. toctree:: + :maxdepth: 2 + + users/resources/index.rst + + .. grid-item:: + + :octicon:`link-external;1em;sd-text-info` `Third-party packages `_, + + provide custom, domain specific, and experimental features, including + styles, colors, more plot types and backends, and alternative + interfaces. + +What's new +========== + +.. grid:: 1 1 2 2 -************ -Contributing -************ + .. grid-item:: + + Learn about new features and API changes. + + .. grid-item:: + + .. toctree:: + :maxdepth: 1 + + users/release_notes.rst + + +Contribute +========== + +.. grid:: 1 1 2 2 + :class-row: sd-align-minor-center + + .. grid-item:: + + Matplotlib is a community project maintained for and by its users. + + There are many ways you can help! + + .. grid-item:: + .. toctree:: + :maxdepth: 2 + + devel/index.rst + +About us +======== + +.. grid:: 1 1 2 2 + :class-row: sd-align-minor-center + + .. grid-item:: + + Matplotlib was created by neurobiologist John Hunter to work with EEG + data. It grew to be used and developed by many people in many + different fields. John's goal was that Matplotlib make easy things easy + and hard things possible. + + .. grid-item:: -Matplotlib is a community project maintained for and by its users. There are many ways -you can help! + .. toctree:: + :maxdepth: 2 -- Help other users `on discourse `__ -- report a bug or request a feature `on GitHub `__ -- or improve the :ref:`documentation and code ` + users/project/index.rst diff --git a/doc/users/index.rst b/doc/users/index.rst index d8c950d57f38..8081b353aeb5 100644 --- a/doc/users/index.rst +++ b/doc/users/index.rst @@ -1,87 +1,100 @@ + .. _users-guide-index: .. redirect-from:: /contents +.. redirect-from:: /users/explain + -########## -User guide -########## +Using Matplotlib +================ .. grid:: 1 1 2 2 - .. grid-item-card:: Starting information - :padding: 2 + .. grid-item-card:: + :padding: 2 + + .. toctree:: + :maxdepth: 2 + :includehidden: + + explain/quick_start + + .. grid-item-card:: + :padding: 2 + + .. toctree:: + :maxdepth: 2 + :includehidden: + + explain/figure/index + + .. grid-item-card:: + :padding: 2 + + .. toctree:: + :maxdepth: 2 + :includehidden: + + explain/axes/index - .. plot:: - rng = np.random.default_rng(seed=19680808) - x = np.linspace(0, 4, 1000) # Sample data. - y = rng.normal(size=len(x)) * 1.5 + x**2 + np.cumsum(rng.normal(size=len(x))) / 6 - x = x[::10] - y = y[::10] - fig, ax = plt.subplots(figsize=(5, 2.7), layout='constrained') + .. grid-item-card:: + :padding: 2 - ax.plot(x, x**2, label='underlying data', linewidth=4, alpha=0.6, color='k') - ax.scatter(x, y, s=13 * rng.random(size=len(x)), c=rng.normal(size=len(x)), - label='noisy data') - # p = np.polyfit(x, y, deg=1) - # print(p) - p = np.array([ 3.81283983, -2.00111268]) - out = np.polyval(p, x) - ax.plot(x, out, label='linear fit') # Plot some data on the axes. - # p = np.polyfit(x, y, deg=2) - # print(p) - p = np.array([ 1.18076933, -0.86768725, 1.05989268]) - out = np.polyval(p, x) - ax.plot(x, out, label='quadratic fit') - ax.set_xlabel('x label') - ax.set_ylabel('y label') - ax.set_title("Simple plot") - ax.legend() + .. toctree:: + :maxdepth: 2 + :includehidden: + explain/artists/index - .. toctree:: - :maxdepth: 1 + .. grid-item-card:: + :padding: 2 - getting_started/index.rst - installing/index.rst - FAQ: How-to and troubleshooting + .. toctree:: + :maxdepth: 2 + :includehidden: - .. grid-item-card:: Users guide - :padding: 2 + explain/customizing - .. toctree:: - :maxdepth: 2 + .. grid-item-card:: + :padding: 2 - explain/index.rst + .. toctree:: + :maxdepth: 2 + :includehidden: - .. grid-item-card:: Tutorials and examples - :padding: 2 + explain/colors/index - .. toctree:: - :maxdepth: 1 + .. grid-item-card:: + :padding: 2 - ../plot_types/index.rst - ../gallery/index.rst - ../tutorials/index.rst - resources/index.rst + .. toctree:: + :maxdepth: 2 + :includehidden: + explain/text/index - .. raw:: html + .. grid-item-card:: + :padding: 2 -
+ .. toctree:: + :maxdepth: 2 + :includehidden: + explain/animations/index - .. grid-item-card:: More information - :padding: 2 + .. grid-item-card:: + :padding: 2 - .. toctree:: - :maxdepth: 1 + .. toctree:: + :maxdepth: 2 + :includehidden: - Reference <../api/index.rst> - Contribute <../devel/index.rst> - Releases + explain/toolkits/index - .. toctree:: - :maxdepth: 2 +.. toctree:: + :hidden: - project/index.rst + explain/index + getting_started/index + installing/index diff --git a/galleries/tutorials/index.rst b/galleries/tutorials/index.rst index 899b3bbcc64e..e51c35a214cd 100644 --- a/galleries/tutorials/index.rst +++ b/galleries/tutorials/index.rst @@ -115,7 +115,7 @@ a :ref:`FAQ ` in our :ref:`user guide `. User guide tutorials -------------------- -Many of our tutorials were moved from this section to :ref:`users-guide-explain`: +Many of our tutorials were moved from this section to :ref:`users-guide-index`: Introductory ~~~~~~~~~~~~ diff --git a/galleries/users_explain/index.rst b/galleries/users_explain/index.rst index 8ed30a9aad8d..46951ede91ab 100644 --- a/galleries/users_explain/index.rst +++ b/galleries/users_explain/index.rst @@ -1,90 +1,5 @@ .. _users-guide-explain: -.. _users-guide-using: -.. redirect-from:: /users/explain - -Using Matplotlib ----------------- - -.. grid:: 1 1 2 2 - - .. grid-item-card:: - :padding: 2 - - .. toctree:: - :maxdepth: 2 - :includehidden: - - quick_start - - .. grid-item-card:: - :padding: 2 - - .. toctree:: - :maxdepth: 2 - :includehidden: - - figure/index - - .. grid-item-card:: - :padding: 2 - - .. toctree:: - :maxdepth: 2 - :includehidden: - - axes/index - - .. grid-item-card:: - :padding: 2 - - .. toctree:: - :maxdepth: 2 - :includehidden: - - artists/index - - .. grid-item-card:: - :padding: 2 - - .. toctree:: - :maxdepth: 2 - :includehidden: - - customizing - - .. grid-item-card:: - :padding: 2 - - .. toctree:: - :maxdepth: 2 - :includehidden: - - colors/index - - .. grid-item-card:: - :padding: 2 - - .. toctree:: - :maxdepth: 2 - :includehidden: - - text/index - - .. grid-item-card:: - :padding: 2 - - .. toctree:: - :maxdepth: 2 - :includehidden: - - animations/index - - .. grid-item-card:: - :padding: 2 - - .. toctree:: - :maxdepth: 2 - :includehidden: - - toolkits/index +==================== +User guide tutorials +====================