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: pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy