From ed86a39c645d91d03e50c21ead8b658550f7b2c0 Mon Sep 17 00:00:00 2001 From: hannah Date: Tue, 25 Jul 2023 18:51:05 -0400 Subject: [PATCH 1/2] content guidelines Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Co-authored-by: Eva Sibinga <46283995+esibinga@users.noreply.github.com> Co-authored-by: melissawm Co-authored-by: Eric Firing Co-authored-by: Thomas A Caswell Co-authored-by: Jody Klymak --- doc/devel/content_guide/api.rst | 11 ++ doc/devel/content_guide/examples.rst | 33 +++++ doc/devel/content_guide/index.rst | 133 +++++++++++++++++ doc/devel/content_guide/plot_types.rst | 14 ++ doc/devel/content_guide/tutorials.rst | 94 ++++++++++++ doc/devel/content_guide/user_guide.rst | 192 +++++++++++++++++++++++++ doc/devel/index.rst | 9 +- doc/devel/tag_guidelines.rst | 29 ---- 8 files changed, 482 insertions(+), 33 deletions(-) create mode 100644 doc/devel/content_guide/api.rst create mode 100644 doc/devel/content_guide/examples.rst create mode 100644 doc/devel/content_guide/index.rst create mode 100644 doc/devel/content_guide/plot_types.rst create mode 100644 doc/devel/content_guide/tutorials.rst create mode 100644 doc/devel/content_guide/user_guide.rst diff --git a/doc/devel/content_guide/api.rst b/doc/devel/content_guide/api.rst new file mode 100644 index 000000000000..231b757fab8a --- /dev/null +++ b/doc/devel/content_guide/api.rst @@ -0,0 +1,11 @@ +.. _content-api: + +API reference +============= + +The API reference documentation describes the library interfaces, e.g. inputs, outputs, +and expected behavior. See :ref:`writing-docstrings` for guidance on writing docstrings. + +The pages in :file:`doc/api` are purely technical definitions of layout; therefore new +API reference documentation should be added to the module docstrings. This placement +keeps all API reference documentation about a module in the same file. diff --git a/doc/devel/content_guide/examples.rst b/doc/devel/content_guide/examples.rst new file mode 100644 index 000000000000..5acb5cbb4286 --- /dev/null +++ b/doc/devel/content_guide/examples.rst @@ -0,0 +1,33 @@ +.. _content-examples: + +Examples gallery +================ + +The gallery of examples contains visual demonstrations of Matplotlib features. Gallery +examples exist so that readers can scan through visual examples. Unlike tutorials or +user guides, gallery examples teach by demonstration, rather than by instruction or +explanation. + +Gallery examples should avoid instruction or excessive explanation except for brief +clarifying code comments. Instead, they can tag related concepts and/or link to relevant +tutorials or user guides. + +Format +------ + +All :ref:`examples-index` should aim to follow the following format: + +* Title: 1-6 words, descriptive of content +* Subtitle: 10-50 words, action-oriented description of the example subject +* Image: a clear demonstration of the subject, showing edge cases and different + applications if possible +* Code + Text (optional): code, commented as appropriate + written text to add context + if necessary + +Example: + +The ``bbox_intersect`` gallery example demonstrates the point of visual examples: + +* this example is "messy" in that it's hard to categorize, but the gallery is the right + spot for it because it makes sense to find it by visual search +* :ref:`sphx_glr_gallery_misc_bbox_intersect.py` diff --git a/doc/devel/content_guide/index.rst b/doc/devel/content_guide/index.rst new file mode 100644 index 000000000000..7873de0edf38 --- /dev/null +++ b/doc/devel/content_guide/index.rst @@ -0,0 +1,133 @@ +.. _documenting-content: + +*************************** +Documentation content guide +*************************** + +These guidelines aim to improve the consistency, cohesiveness, and organization of the +:ref: documentation concerning using the library by broadly articulating the intended purpose, +scope, and audience of each of the following sections: + +:ref:`plot_types` + | Summary of chart types that are implemented as high-level API + +:ref:`User guide ` + | Explanations of features, components, and architecture. + +:ref:`tutorials` + | Lessons on developing visualizations + +:ref:`examples-index` + | Demonstrations of specific library features + +:ref:`api-reference` + | Descriptions of the public modules, objects, methods, and functions. + + +.. note:: + + While parts of the current documentation may not yet align with these guidelines, + we expect that new documentation contributions will also bring existing documentation + into alignment. + + .. note: based on note in https://matplotlib.org/3.7.3/devel/coding_guide.html + + + +Guidelines +========== + +This content guide is heavily influenced by the `Diátaxis `_ +framework for technical documentation; this framework proposes that all technical +documentation is roughly one of 4 types - tutorials, how-to-guides, +technical reference, and explanation - and that the appropriate type is determined +by whether *what* is x? (cognition) vs *how* to do x?(action) is being documented, and +whether the document's purpose is *acquiring* (learning) or *applying* (using) skills. + +Broadly, our documentation as viewed through a diátaxis lens: + +.. list-table:: + :header-rows: 1 + :widths: 20 30 20 30 + + * - section + - goal + - type + - example + * - :ref:`plot_types` + - View available chart types. + - | `Reference `_ + | what, use + - :ref:`sphx_glr_plot_types_stats_pie.py` + * - :ref:`User guide ` + - Understand features, components, and architecture + - | `Explanation `_ + | what, learn + - :ref:`annotations` + * - :ref:`tutorials` + - Work through the stages of building a visualization. + - | `Tutorials `_ + | how, learn + - :ref:`sphx_glr_gallery_pie_and_polar_charts_pie_and_donut_labels.py` + * - :ref:`examples-index` + - Execute a visualization task. + - | `How-to guides `_ + | how, use + - :ref:`sphx_glr_gallery_text_labels_and_annotations_rainbow_text.py` + * - :ref:`api-reference` + - Look up the input/output/behavior of public API. + - | `Reference `_ + | what, use + - `.Axes.annotate` + +Detailed guidelines for each section are documented at their respective pages: + +.. toctree:: + :maxdepth: 1 + + plot_types + user_guide + tutorials + examples + api + + +Audience +======== + +The Matplotlib audience encompasses a wide spectrum of readers, from users who are first +getting introduced to using Matplotlib through the documentation to experienced developers +who want to make something extremely customized. Instead of trying to write for the +entire spectrum, each document should identify its band so that reader can assess +whether the document is appropriate for them. The documentation should generally use the +leveling of :doc:`tags <../tag_guidelines>` and :ref:`issues `, meaning +that the audienced is identified based on how much contextual understanding of +Matplotlib is a pre-requisite for following along with the document. + +Documents can communicate this leveling through tags, location in the docs, and in text +as appropriate. For example: + + This guide assumes that the reader understands the general concept of Artists, as + explained in :ref:`users_artists` + + +Scope +===== +Many concepts in Matplotlib assume a grounding in visualization, statistics, Python +programming, and other topics to understand how they work. These concepts should be +contextualized using common terminology, but the focus for all documents should not +stray from the Matplotlib topic. For example: + + Some of the path components require multiple vertices to specify them: for example + CURVE 3 is a `Bézier curve `_ with + one control point and one end point, and CURVE4 has three vertices for the two + control points and the end point. The example below shows a CURVE4 Bézier spline -- + the Bézier curve will be contained in the convex hull of the start point, the two + control points, and the end point + + +This explanation of drawing a curve using control points from :ref:`paths` never +explicitly defines a *Bézier curve*, instead linking out to an external +reference. This explanation is written in a manner where the definition of +*Bézier curve* can be inferred from context and also understanding is not harmed if the +reader does not infer the definition. diff --git a/doc/devel/content_guide/plot_types.rst b/doc/devel/content_guide/plot_types.rst new file mode 100644 index 000000000000..a708c29c5f69 --- /dev/null +++ b/doc/devel/content_guide/plot_types.rst @@ -0,0 +1,14 @@ +.. _content-plot-types: + +Plot types gallery +================== + +The plot type gallery displays a selection of the common visualization techniques that +are implemented in Matplotlib. The gallery is heavily curated and tightly scoped to the +plotting methods on `matplotlib.axes.Axes` so additions are generally discouraged. + +Format +------ +* very short: 5-10 lines +* self explanatory data +* little to no customization. diff --git a/doc/devel/content_guide/tutorials.rst b/doc/devel/content_guide/tutorials.rst new file mode 100644 index 000000000000..5a8dfb7395b8 --- /dev/null +++ b/doc/devel/content_guide/tutorials.rst @@ -0,0 +1,94 @@ +.. _content-tutorials: + +Tutorials +========= + +The goal of the tutorials is to guide the reader through the stages of using Matplotlib +to build specific visualization. The tutorials focus on learning how to combine the +features and components that were explained in the user guide. + +Format +------ + +As with the user guide, the tutorials should aim to unpack information in chunks and +build on the previous section. + +Where the user guide explains topics like plotting and animation separately, a tutorial +walks the reader through the steps involved in animating a line plot. Generally the +content is limited to describing what is happening at each stage- for example there's no +explanation of why an update function is written-and instead the reader is linked to an +explanation. + +#. First we start by stating the objective: + + .. code-block:: rst + + The goal of this tutorial is to create an animated sin wave. + +#. Then we describe what needs to be in place to do the task. Here that is the data and + object that we will animate: + + .. code-block:: rst + + First lets generate a sin wave:: + + x = np.linspace(0, 2*np.pi, 1000) + y = np.sin(x) + + Then we plot an empty line and capture the returned line object:: + + fig, ax = plt.subplot() + l, _ = ax.plot(0,0) + +#. With our pieces in place, we instruct the reader on how to animate the object: + + .. code-block:: rst + + Next we write a function that changes the plot on each frame. Here we grow the sin + curve on each update by setting the new x and y data:: + + def update(frame): + + l.set_data(x[:i], y[:i]) + +#. Next we show them how to generate the animation and describe the arguments: + + .. code-block:: rst + + Lastly we add an animation writer. Here we specify 30 milliseconds between each + of the 40 frames:: + + ani = animation.FuncAnimation(fig=fig, func=update, frames=40, interval=30) + +#. Then we put all the steps together to make the animated sin wave: + + .. code-block:: rst + + Now lets put it all together so we can plot an animated sin curve:: + + x = np.linspace(0, 2*np.pi, 1000) + y = np.sin(x) + + fig, ax = plt.subplot() + l, _ = ax.plot(0,0) + + def update(frame): + l.set_data(x[:i], y[:i]) + + ani = animation.FuncAnimation(fig=fig, func=update, frames=40, interval=30) + +#. Finally, we close with a follow up call to action to learn about the underlying + concepts: + + .. code-block:: rst + + For more information on animations and lines, see: + * :ref:`animations` + * ``:ref:Line2d`` + + +Please note that while the aim is to show how to animate a sin curve, the focus is +always on making the animation. Generally explanations of domain should be limited to +providing contextually necessary information, and tutorials that are heavily domain +specific may be more appropriate for the Scientific Python +`blog `_. diff --git a/doc/devel/content_guide/user_guide.rst b/doc/devel/content_guide/user_guide.rst new file mode 100644 index 000000000000..23e8351455ed --- /dev/null +++ b/doc/devel/content_guide/user_guide.rst @@ -0,0 +1,192 @@ +.. _content-user-guide: + +User guide +========== + +The user guide explains what the reader needs to know to *make* and *customize* +visualizations, and *develop* tools and downstream libraries: + ++-----------+---------------+-----------------------------------------------------+ +| section | focus | purpose | ++===========+===============+=====================================================+ +| Make | Features | Provide overview of library features | ++-----------+---------------+-----------------------------------------------------+ +| Customize | Components | Review what each component does | ++-----------+---------------+-----------------------------------------------------+ +| Develop | Architecture | Explain implementation details and design decisions | ++-----------+---------------+-----------------------------------------------------+ + +Each section builds on the previous to expand the reader's conceptal understanding of +the library so that the user can develop a mental model (schema) of how Matplotlib +operates. The goal is that understanding how the features, components, and architecture +fit together empowers the user to piece together solutions from existing documentation. + +.. _content-user-guide-make: + +Make +----- + +The goal of this section is to provide an overview of using Matplotlib to make things. +Therefore, content should be generalized rather than focused on specific tasks, e.g. +*what is the usage pattern for making plots?* rather than *How do I make a squiggly +yellow line?* + + +Audience +^^^^^^^^ + +This section of the user guide assumes that it is the readers first introduction to +Matplotlib. Therefore, the reader may not yet know what Matplotlib calls a given v +isualization task nor how any task is accomplished in Matplotlib. Those documents should +first introduce or define the object/module/concept that it is discussing and why it is +important for the reader. e.g.: + + A matplotlib visualization is managed by a `~.Figure` object onto which is attached + one or more `~.matplotlib.axes.Axes` objects. Each Axes object manages a plotting + region. The coordinate system of this region is managed by `~.matplotlib.axis.Axis` + objects; often these are x Axis and y Axis objects. + + +While a lot more can be said for each of the objects introduced here, that level of +detail is out of scope for the getting started guide. Here the goal is to provide just +enough vocabulary so that readers can follow along with the rest of the guide. + +Generally this section of the user guide should be written with the assumption that it +is read linearlly. + +Format +^^^^^^ + +When possible, the material is introduced in tightly scoped sections that build on top +of each other, using teaching strategies called `chunking and scaffolding`_. +Chunking is aimed at reducing `cognitive load`_ by keeping the focus of each section +relatively small, and scaffolding lays out instructional material such that each section +builds on the previous one. + +.. code-block:: rst + :caption: Example: make + + A matplotlib visualization is managed by a `~.Figure` object onto which is attached + one or more `~.matplotlib.axes.Axes` objects. Each Axes object manages a plotting + region. The coordinate system of this region is managed by `~.matplotlib.axis.Axis` + objects; often these are x Axis and y Axis objects. + + Generally, visualizations are created by first creating a `~.Figure` and + `~.matplotlib.axes.Axes`, and then calling plotting methods on that axes: + + For example, to make a line plot:: + + fig, ax = plt.subplots() + ax.plot([1,2,3], [2,1,2]) + + Making a bar plot follows the same format:: + + fig, ax = plt.subplots() + ax.bar([1,2,3], [2,1,2]) + + As does an image, with the input changed to a 2D array:: + + fig, ax = plt.subplots() + ax.imshow([[1,2,3], [2,1,2]]) + +Here this example is very tightly scoped to how to make a single plot. The goal of these +small and repetitive examples is to reinforce that making visualizations, regardless of +chart type, follows the same basic pattern of: 1) create figure and axes, 2) call +plotting method with data. For some topics and examples, it may be preferable to take +the inverse approach: start with a complex example and then unpack it into its pieces. + +In general, this approach is aimed at helping the reader develop a model of the concept +by first defining it and then illustrating how that understanding facilitates better use +of the library. In keeping with this goal, documents should also be tightly focused on +one topic and link out to related material, e.g. *insert explanation* + +.. _`chunking and scaffolding`: https://www.tacoma.uw.edu/digital-learning/chunking-scaffolding-pacing +.. _`cognitive load`: https://carpentries.github.io/instructor-training/05-memory.html + + +.. _content-user-guide-customize: + +Customize +--------- + +The goal of this section is to explain how the components of the library can be used to +customize visualizations. + +Audience +^^^^^^^^ + +This section assumes that the reader understands how to make visualizations using +Matplotlib but does not yet have a solid mental model of what the various components of +the library are responsible for or how they fit together. For example, they know how to +set the color of a heatmap using the ``cmap``` keyword and are now interested in +learning about colormaps and normalization. The documents in this section are generally +assumed to be accessed independent of each other unless cross referenced. + +Format +^^^^^^ + +Similar to the :ref:`content-user-guide-make` section, the documents in this section +aim to provide a review of using the component and generally aim to do so in a +scaffolded and chunked manner. + +.. code-block:: rst + :caption: Example: customize + + A `~.Figure` is roughly the total drawing area and keeps track of the child + `~matplotlib.axes.Axes`, figure related artists such as titles, figure legends, + colorbars, and nested subfigures. + + Generally Figures are created through helper methods that also create Axes objects, + as discussed in :ref:`arranging_axes`. Here we create a Figure without an Axes to + isolate manipulating Figure object:: + + fig = plt.figure() + + The Figure size on the screen is set by figsize and dpi; figsize is the + (width, height) of the Figure in inches or units of 72 typographic points, while + dpi is how many pixels per inch the figure will be rendered at. Here we set the + figure size to be a :math:`5 \times 5` square :: + + fig = plt.figure(figsize=(5,5)) + + To make your Figures appear on the screen at the physical size you requested, you + should set dpi to the same dpi as your graphics system. + +Here this example unpacks the `~.Figure` object that was briefly mentioned in the +previous example. It describes the `~.Figure` object in more detail, then explains how +to create an object and links out to the guide that discusses other ways of doing so, +then shows the frequent use case of changing the figure size. The goal of this example +is to help the reader understand what they can do with a `.Figure` object. + +.. _content-user-guide-extend: + +Develop +------- + +The goal of this section is to explain the design considerations and implementation +details necessary for building downstream libraries using Matplotlib. + +Audience +^^^^^^^^ +This section assumes that the reader is a downstream library developer. This reader has +a solid mental model of the library and needs to understand underlying design decisions +and implementation details so that they can build extensions such as custom Artists or +projections. The documents in this section are generally assumed to be accessed +independent of each other unless cross referenced. + +Format +^^^^^^ +Like the other sections, explanations into buildable well scoped chunks. As mentioned, +the primary difference is that the content will focus on implementation details because +the goal is to explain how the parts of the library work. + +.. code-block:: rst + :caption: Example: develop + + ``pyplot.figure()`` can create a new `~.Figure` instance and associate it with an + instance of a backend-provided canvas class, itself hosted in an instance of a + backend-provided manager class. + +Building on the assumption that the user is familiar with the Figure object, this +section dives straight into what the ``pyplot.figure()`` method does when creating +Figures. diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 3ddbcba198a0..66db0c129bb6 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -1,8 +1,8 @@ .. _developers-guide-index: -########## +********** Contribute -########## +********** .. ifconfig:: releaselevel != 'dev' @@ -151,8 +151,9 @@ Policies and guidelines :maxdepth: 1 document - style_guide - tag_guidelines + style guide + content guide + tagging guidelines .. grid-item-card:: :shadow: none diff --git a/doc/devel/tag_guidelines.rst b/doc/devel/tag_guidelines.rst index ca6b8cfde01d..b8b66c1030ca 100644 --- a/doc/devel/tag_guidelines.rst +++ b/doc/devel/tag_guidelines.rst @@ -44,32 +44,3 @@ Note: Tagging organization aims to work for 80-90% of cases. Some examples fall How to tag? ----------- Put each tag as a directive at the bottom of the page. - -Related content ---------------- - -What is a gallery example? -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The gallery of examples contains visual demonstrations of matplotlib features. Gallery examples exist so that users can scan through visual examples. - -Unlike tutorials or user guides, gallery examples teach by demonstration, rather than by explanation or instruction. - -Gallery examples should avoid instruction or excessive explanation except for brief clarifying code comments. Instead, they can tag related concepts and/or link to relevant tutorials or user guides. - -Format -^^^^^^ - -All :ref:`examples-index` should aim to follow the following format: - -* Title: 1-6 words, descriptive of content -* Subtitle: 10-50 words, action-oriented description of the example subject -* Image: a clear demonstration of the subject, showing edge cases and different applications if possible -* Code + Text (optional): code, commented as appropriate + written text to add context if necessary - -Example: - -The ``bbox_intersect`` gallery example demonstrates the point of visual examples: - -* this example is "messy" in that it's hard to categorize, but the gallery is the right spot for it because it makes sense to find it by visual search -* https://matplotlib.org/devdocs/gallery/misc/bbox_intersect.html#sphx-glr-gallery-misc-bbox-intersect-py From cac413331e1081aff4372802c5cce2ba1c7b7bbd Mon Sep 17 00:00:00 2001 From: hannah Date: Tue, 13 Feb 2024 15:26:10 -0500 Subject: [PATCH 2/2] summary user guide --- doc/devel/content_guide.rst | 283 +++++++++++++++++++ doc/devel/content_guide/api.rst | 11 - doc/devel/content_guide/examples.rst | 33 --- doc/devel/content_guide/index.rst | 133 --------- doc/devel/content_guide/plot_types.rst | 14 - doc/devel/content_guide/tutorials.rst | 94 ------ doc/devel/index.rst | 6 +- doc/devel/{content_guide => }/user_guide.rst | 18 +- 8 files changed, 299 insertions(+), 293 deletions(-) create mode 100644 doc/devel/content_guide.rst delete mode 100644 doc/devel/content_guide/api.rst delete mode 100644 doc/devel/content_guide/examples.rst delete mode 100644 doc/devel/content_guide/index.rst delete mode 100644 doc/devel/content_guide/plot_types.rst delete mode 100644 doc/devel/content_guide/tutorials.rst rename doc/devel/{content_guide => }/user_guide.rst (94%) diff --git a/doc/devel/content_guide.rst b/doc/devel/content_guide.rst new file mode 100644 index 000000000000..735574be3f4a --- /dev/null +++ b/doc/devel/content_guide.rst @@ -0,0 +1,283 @@ +.. _documenting-content: + +*************************** +Documentation content guide +*************************** + +These guidelines aim to improve the consistency, cohesiveness, and organization of the +:ref: documentation concerning using the library by broadly articulating the intended purpose, +scope, and audience of each of the following sections: + +:ref:`plot_types` + | Summary of chart types that are implemented as high-level API + +:ref:`User guide ` + | Explanations of features, components, and architecture. + +:ref:`tutorials` + | Lessons on developing visualizations + +:ref:`examples-index` + | Demonstrations of specific library features + +:ref:`api-reference` + | Descriptions of the public modules, objects, methods, and functions. + + +.. note:: + + While parts of the current documentation may not yet align with these guidelines, + we expect that new documentation contributions will also bring existing documentation + into alignment. + + .. note: based on note in https://matplotlib.org/3.7.3/devel/coding_guide.html + + + +Summary +========== + +This content guide is heavily influenced by the `Diátaxis `_ +framework for technical documentation; this framework proposes that all +technical documentation is roughly one of 4 types - tutorials, how-to-guides, +technical reference, and explanation - and that the appropriate type is +determined by whether the document focuses on *what* is x? (cognition) or *how* +to do x?(action), and whether the document's purpose is *acquiring* (learning) +or *applying* (using) skills. + +Broadly, our documentation as viewed through a diátaxis lens: + +.. list-table:: + :header-rows: 1 + :widths: 20 30 20 30 + + * - section + - goal + - type + - example + * - :ref:`plot_types` + - View available chart types. + - | `Reference `_ + | what, use + - :ref:`sphx_glr_plot_types_stats_pie.py` + * - :ref:`User guide ` + - Understand features, components, and architecture + - | `Explanation `_ + | what, learn + - :ref:`annotations` + * - :ref:`tutorials` + - Work through the stages of building a visualization. + - | `Tutorials `_ + | how, learn + - :ref:`sphx_glr_gallery_pie_and_polar_charts_pie_and_donut_labels.py` + * - :ref:`examples-index` + - Execute a visualization task. + - | `How-to guides `_ + | how, use + - :ref:`sphx_glr_gallery_text_labels_and_annotations_rainbow_text.py` + * - :ref:`api-reference` + - Look up the input/output/behavior of public API. + - | `Reference `_ + | what, use + - `.Axes.annotate` + +Audience +-------- +The Matplotlib audience encompasses a wide spectrum of readers, from users who are first +getting introduced to using Matplotlib through the documentation to experienced developers +who want to make something extremely customized. Instead of trying to write for the +entire spectrum, each document should identify its band so that reader can assess +whether the document is appropriate for them. The documentation should generally use the +leveling of :doc:`tags ` and :ref:`issues `, meaning +that the audienced is identified based on how much contextual understanding of +Matplotlib is a pre-requisite for following along with the document. + +Documents can communicate this leveling through tags, location in the docs, and in text +as appropriate. For example: + + This guide assumes that the reader understands the general concept of Artists, as + explained in :ref:`users_artists` + + +Scope +----- +Many concepts in Matplotlib assume a grounding in visualization, statistics, Python +programming, and other topics to understand how they work. These concepts should be +contextualized using common terminology, but the focus for all documents should not +stray from the Matplotlib topic. For example: + + Some of the path components require multiple vertices to specify them: for example + CURVE 3 is a `Bézier curve `_ with + one control point and one end point, and CURVE4 has three vertices for the two + control points and the end point. The example below shows a CURVE4 Bézier spline -- + the Bézier curve will be contained in the convex hull of the start point, the two + control points, and the end point + + +This explanation of drawing a curve using control points from :ref:`paths` never +explicitly defines a *Bézier curve*, instead linking out to an external +reference. This explanation is written in a manner where the definition of +*Bézier curve* can be inferred from context and also understanding is not harmed if the +reader does not infer the definition. + + +.. _content-plot-types: + +Plot types gallery +================== + +The plot type gallery displays a selection of the common visualization techniques that +are implemented in Matplotlib. The gallery is heavily curated and tightly scoped to the +plotting methods on `matplotlib.axes.Axes` so additions are generally discouraged. + +Format +------ +* very short: 5-10 lines +* self explanatory data +* little to no customization. + +.. _content-user-guide: + +User guide +========== + +.. toctree:: + :hidden: + + user_guide + +.. include:: user_guide.rst + :start-after: summary-begin + :end-before: summary-end + +For more details, see :ref:`user-guide-content-detail` + +.. _content-tutorials: + +Tutorials +========= + +The goal of the tutorials is to guide the reader through the stages of using +Matplotlib to build a specific visualization. A tutorial describes what is +happening at each stage of executing a visualization task and links to the +user guide and API for explanations. + +Format +------ + +The sample tutorial here is trivial to highlight the step-wise format: + +#. First we start by stating the objective: + + .. code-block:: rst + + The goal of this tutorial is to animate a sin wave. + +#. Then we describe what needs to be in place to do the task: + + .. code-block:: rst + + First lets generate a sin wave:: + + x = np.linspace(0, 2*np.pi, 1000) + y = np.sin(x) + + Then we plot an empty line and capture the returned line object:: + + fig, ax = plt.subplot() + l, _ = ax.plot(0,0) + +#. Next we walk the reader through each step of executing the task: + + .. code-block:: rst + + Next we write a function that changes the plot on each frame. Here we grow + the sin curve on each update by setting the new x and y data:: + + def update(frame): + + l.set_data(x[:i], y[:i]) + + Lastly we add an animation writer. Here we specify 30 milliseconds between each + of the 40 frames:: + + ani = animation.FuncAnimation(fig=fig, func=update, frames=40, interval=30) + +#. Then we summarize by putting all the steps together: + + .. code-block:: rst + + Now lets put it all together so we can plot an animated sin curve:: + + x = np.linspace(0, 2*np.pi, 1000) + y = np.sin(x) + + fig, ax = plt.subplot() + l, _ = ax.plot(0,0) + + def update(frame): + l.set_data(x[:i], y[:i]) + + ani = animation.FuncAnimation(fig=fig, func=update, frames=40, interval=30) + +#. Finally, we close with a call to action to learn about the underlying concepts: + + .. code-block:: rst + + For more information on animations and lines, see: + * :ref:`animations` + * ``:ref:Line2d`` + +Please note that explanations of domain should be limited to providing +contextually necessary information, and tutorials that are heavily domain +specific may be more appropriate for the Scientific Python +`blog `_. + + + +.. _content-examples: + +Examples gallery +================ + +The gallery of examples contains visual demonstrations of Matplotlib features. Gallery +examples exist so that readers can scan through visual examples. Unlike tutorials or +user guides, gallery examples teach by demonstration, rather than by instruction or +explanation. + +Gallery examples should avoid instruction or excessive explanation except for brief +clarifying code comments. Instead, they can tag related concepts and/or link to relevant +tutorials or user guides. + +Format +------ + +All :ref:`examples-index` should aim to follow the following format: + +* Title: 1-6 words, descriptive of content +* Subtitle: 10-50 words, action-oriented description of the example subject +* Image: a clear demonstration of the subject, showing edge cases and different + applications if possible +* Code + Text (optional): code, commented as appropriate + written text to add context + if necessary + +Example: + +The ``bbox_intersect`` gallery example demonstrates the point of visual examples: + +* this example is "messy" in that it's hard to categorize, but the gallery is the right + spot for it because it makes sense to find it by visual search +* :ref:`sphx_glr_gallery_misc_bbox_intersect.py` + + +.. _content-api: + +API reference +============= + +The API reference documentation describes the library interfaces, e.g. inputs, outputs, +and expected behavior. See :ref:`writing-docstrings` for guidance on writing docstrings. + +The pages in :file:`doc/api` are purely technical definitions of layout; therefore new +API reference documentation should be added to the module docstrings. This placement +keeps all API reference documentation about a module in the same file. diff --git a/doc/devel/content_guide/api.rst b/doc/devel/content_guide/api.rst deleted file mode 100644 index 231b757fab8a..000000000000 --- a/doc/devel/content_guide/api.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _content-api: - -API reference -============= - -The API reference documentation describes the library interfaces, e.g. inputs, outputs, -and expected behavior. See :ref:`writing-docstrings` for guidance on writing docstrings. - -The pages in :file:`doc/api` are purely technical definitions of layout; therefore new -API reference documentation should be added to the module docstrings. This placement -keeps all API reference documentation about a module in the same file. diff --git a/doc/devel/content_guide/examples.rst b/doc/devel/content_guide/examples.rst deleted file mode 100644 index 5acb5cbb4286..000000000000 --- a/doc/devel/content_guide/examples.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _content-examples: - -Examples gallery -================ - -The gallery of examples contains visual demonstrations of Matplotlib features. Gallery -examples exist so that readers can scan through visual examples. Unlike tutorials or -user guides, gallery examples teach by demonstration, rather than by instruction or -explanation. - -Gallery examples should avoid instruction or excessive explanation except for brief -clarifying code comments. Instead, they can tag related concepts and/or link to relevant -tutorials or user guides. - -Format ------- - -All :ref:`examples-index` should aim to follow the following format: - -* Title: 1-6 words, descriptive of content -* Subtitle: 10-50 words, action-oriented description of the example subject -* Image: a clear demonstration of the subject, showing edge cases and different - applications if possible -* Code + Text (optional): code, commented as appropriate + written text to add context - if necessary - -Example: - -The ``bbox_intersect`` gallery example demonstrates the point of visual examples: - -* this example is "messy" in that it's hard to categorize, but the gallery is the right - spot for it because it makes sense to find it by visual search -* :ref:`sphx_glr_gallery_misc_bbox_intersect.py` diff --git a/doc/devel/content_guide/index.rst b/doc/devel/content_guide/index.rst deleted file mode 100644 index 7873de0edf38..000000000000 --- a/doc/devel/content_guide/index.rst +++ /dev/null @@ -1,133 +0,0 @@ -.. _documenting-content: - -*************************** -Documentation content guide -*************************** - -These guidelines aim to improve the consistency, cohesiveness, and organization of the -:ref: documentation concerning using the library by broadly articulating the intended purpose, -scope, and audience of each of the following sections: - -:ref:`plot_types` - | Summary of chart types that are implemented as high-level API - -:ref:`User guide ` - | Explanations of features, components, and architecture. - -:ref:`tutorials` - | Lessons on developing visualizations - -:ref:`examples-index` - | Demonstrations of specific library features - -:ref:`api-reference` - | Descriptions of the public modules, objects, methods, and functions. - - -.. note:: - - While parts of the current documentation may not yet align with these guidelines, - we expect that new documentation contributions will also bring existing documentation - into alignment. - - .. note: based on note in https://matplotlib.org/3.7.3/devel/coding_guide.html - - - -Guidelines -========== - -This content guide is heavily influenced by the `Diátaxis `_ -framework for technical documentation; this framework proposes that all technical -documentation is roughly one of 4 types - tutorials, how-to-guides, -technical reference, and explanation - and that the appropriate type is determined -by whether *what* is x? (cognition) vs *how* to do x?(action) is being documented, and -whether the document's purpose is *acquiring* (learning) or *applying* (using) skills. - -Broadly, our documentation as viewed through a diátaxis lens: - -.. list-table:: - :header-rows: 1 - :widths: 20 30 20 30 - - * - section - - goal - - type - - example - * - :ref:`plot_types` - - View available chart types. - - | `Reference `_ - | what, use - - :ref:`sphx_glr_plot_types_stats_pie.py` - * - :ref:`User guide ` - - Understand features, components, and architecture - - | `Explanation `_ - | what, learn - - :ref:`annotations` - * - :ref:`tutorials` - - Work through the stages of building a visualization. - - | `Tutorials `_ - | how, learn - - :ref:`sphx_glr_gallery_pie_and_polar_charts_pie_and_donut_labels.py` - * - :ref:`examples-index` - - Execute a visualization task. - - | `How-to guides `_ - | how, use - - :ref:`sphx_glr_gallery_text_labels_and_annotations_rainbow_text.py` - * - :ref:`api-reference` - - Look up the input/output/behavior of public API. - - | `Reference `_ - | what, use - - `.Axes.annotate` - -Detailed guidelines for each section are documented at their respective pages: - -.. toctree:: - :maxdepth: 1 - - plot_types - user_guide - tutorials - examples - api - - -Audience -======== - -The Matplotlib audience encompasses a wide spectrum of readers, from users who are first -getting introduced to using Matplotlib through the documentation to experienced developers -who want to make something extremely customized. Instead of trying to write for the -entire spectrum, each document should identify its band so that reader can assess -whether the document is appropriate for them. The documentation should generally use the -leveling of :doc:`tags <../tag_guidelines>` and :ref:`issues `, meaning -that the audienced is identified based on how much contextual understanding of -Matplotlib is a pre-requisite for following along with the document. - -Documents can communicate this leveling through tags, location in the docs, and in text -as appropriate. For example: - - This guide assumes that the reader understands the general concept of Artists, as - explained in :ref:`users_artists` - - -Scope -===== -Many concepts in Matplotlib assume a grounding in visualization, statistics, Python -programming, and other topics to understand how they work. These concepts should be -contextualized using common terminology, but the focus for all documents should not -stray from the Matplotlib topic. For example: - - Some of the path components require multiple vertices to specify them: for example - CURVE 3 is a `Bézier curve `_ with - one control point and one end point, and CURVE4 has three vertices for the two - control points and the end point. The example below shows a CURVE4 Bézier spline -- - the Bézier curve will be contained in the convex hull of the start point, the two - control points, and the end point - - -This explanation of drawing a curve using control points from :ref:`paths` never -explicitly defines a *Bézier curve*, instead linking out to an external -reference. This explanation is written in a manner where the definition of -*Bézier curve* can be inferred from context and also understanding is not harmed if the -reader does not infer the definition. diff --git a/doc/devel/content_guide/plot_types.rst b/doc/devel/content_guide/plot_types.rst deleted file mode 100644 index a708c29c5f69..000000000000 --- a/doc/devel/content_guide/plot_types.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _content-plot-types: - -Plot types gallery -================== - -The plot type gallery displays a selection of the common visualization techniques that -are implemented in Matplotlib. The gallery is heavily curated and tightly scoped to the -plotting methods on `matplotlib.axes.Axes` so additions are generally discouraged. - -Format ------- -* very short: 5-10 lines -* self explanatory data -* little to no customization. diff --git a/doc/devel/content_guide/tutorials.rst b/doc/devel/content_guide/tutorials.rst deleted file mode 100644 index 5a8dfb7395b8..000000000000 --- a/doc/devel/content_guide/tutorials.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. _content-tutorials: - -Tutorials -========= - -The goal of the tutorials is to guide the reader through the stages of using Matplotlib -to build specific visualization. The tutorials focus on learning how to combine the -features and components that were explained in the user guide. - -Format ------- - -As with the user guide, the tutorials should aim to unpack information in chunks and -build on the previous section. - -Where the user guide explains topics like plotting and animation separately, a tutorial -walks the reader through the steps involved in animating a line plot. Generally the -content is limited to describing what is happening at each stage- for example there's no -explanation of why an update function is written-and instead the reader is linked to an -explanation. - -#. First we start by stating the objective: - - .. code-block:: rst - - The goal of this tutorial is to create an animated sin wave. - -#. Then we describe what needs to be in place to do the task. Here that is the data and - object that we will animate: - - .. code-block:: rst - - First lets generate a sin wave:: - - x = np.linspace(0, 2*np.pi, 1000) - y = np.sin(x) - - Then we plot an empty line and capture the returned line object:: - - fig, ax = plt.subplot() - l, _ = ax.plot(0,0) - -#. With our pieces in place, we instruct the reader on how to animate the object: - - .. code-block:: rst - - Next we write a function that changes the plot on each frame. Here we grow the sin - curve on each update by setting the new x and y data:: - - def update(frame): - - l.set_data(x[:i], y[:i]) - -#. Next we show them how to generate the animation and describe the arguments: - - .. code-block:: rst - - Lastly we add an animation writer. Here we specify 30 milliseconds between each - of the 40 frames:: - - ani = animation.FuncAnimation(fig=fig, func=update, frames=40, interval=30) - -#. Then we put all the steps together to make the animated sin wave: - - .. code-block:: rst - - Now lets put it all together so we can plot an animated sin curve:: - - x = np.linspace(0, 2*np.pi, 1000) - y = np.sin(x) - - fig, ax = plt.subplot() - l, _ = ax.plot(0,0) - - def update(frame): - l.set_data(x[:i], y[:i]) - - ani = animation.FuncAnimation(fig=fig, func=update, frames=40, interval=30) - -#. Finally, we close with a follow up call to action to learn about the underlying - concepts: - - .. code-block:: rst - - For more information on animations and lines, see: - * :ref:`animations` - * ``:ref:Line2d`` - - -Please note that while the aim is to show how to animate a sin curve, the focus is -always on making the animation. Generally explanations of domain should be limited to -providing contextually necessary information, and tutorials that are heavily domain -specific may be more appropriate for the Scientific Python -`blog `_. diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 66db0c129bb6..46885ee00a00 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -151,9 +151,9 @@ Policies and guidelines :maxdepth: 1 document - style guide - content guide - tagging guidelines + Style guide + Content guide + Tagging guidelines .. grid-item-card:: :shadow: none diff --git a/doc/devel/content_guide/user_guide.rst b/doc/devel/user_guide.rst similarity index 94% rename from doc/devel/content_guide/user_guide.rst rename to doc/devel/user_guide.rst index 23e8351455ed..3f0ff9788611 100644 --- a/doc/devel/content_guide/user_guide.rst +++ b/doc/devel/user_guide.rst @@ -1,7 +1,9 @@ -.. _content-user-guide: +.. _user-guide-content-detail: -User guide -========== +User guide content guide +======================== + +.. summary-begin The user guide explains what the reader needs to know to *make* and *customize* visualizations, and *develop* tools and downstream libraries: @@ -18,8 +20,14 @@ visualizations, and *develop* tools and downstream libraries: Each section builds on the previous to expand the reader's conceptal understanding of the library so that the user can develop a mental model (schema) of how Matplotlib -operates. The goal is that understanding how the features, components, and architecture -fit together empowers the user to piece together solutions from existing documentation. +operates. For example, *make* introduces the concept of making figures, +*customize* explains what the user can do with figures, and *develop* discusses +how the Figure object works in the context of the other parts of the library. The +goal is that understanding how the features, components, and architecture fit +together empowers the user to piece together solutions from existing +documentation. + +.. summary-end .. _content-user-guide-make: