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/index.rst b/doc/devel/index.rst index 3ddbcba198a0..46885ee00a00 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 diff --git a/doc/devel/user_guide.rst b/doc/devel/user_guide.rst new file mode 100644 index 000000000000..3f0ff9788611 --- /dev/null +++ b/doc/devel/user_guide.rst @@ -0,0 +1,200 @@ +.. _user-guide-content-detail: + +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: + ++-----------+---------------+-----------------------------------------------------+ +| 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. 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: + +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.