8000 standalone content guide · matplotlib/matplotlib@d3ee51b · GitHub
[go: up one dir, main page]

Skip to content

Commit d3ee51b

Browse files
committed
standalone content guide
1 parent 4eda4e8 commit d3ee51b

File tree

2 files changed

+0
-127
lines changed

2 files changed

+0
-127
lines changed

doc/devel/document.rst

Lines changed: 0 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1005,7 +1005,6 @@ Functions that exist in ``pyplot`` as well as in Axes or Figure should mention
10051005
both references no matter which one is used in the example code. The ``pyplot``
10061006
reference should always be the second to mention; see the example above.
10071007

1008-
10091008
Order examples
10101009
--------------
10111010

@@ -1046,103 +1045,6 @@ any ``*.rst`` files to a ``:toctree:``, either in the ``README.txt`` or in a
10461045
manual ``index.rst``.
10471046

10481047

1049-
.. _writing-user-guide:
1050-
1051-
Write user guide documentation
1052-
==============================
1053-
1054-
The pages in the :ref:`users-guide-index` are a mix of :ref:`ReST <writing-rest-pages>`
1055-
and :ref:`sphinx gallery <writing-examples-and-tutorials>` pages and should follow the
1056-
respective formatting conventions. The goal of the user guide is to explain how
1057-
Matplotlib works to someone who is unfamiliar with the library. To maintain the
1058-
consistency and cohesiveness of the user guide, documentation that is contributed to
1059-
this section should conform to the following guidelines:
1060-
1061-
Purpose: Explain how Matplotlib works
1062-
-------------------------------------
1063-
1064-
The aim of the user guide is to teach the conceptual abstractions on which the
1065-
Matplotlib API is developed so that users can understand how to fit the individual
1066-
components of the library together. Therefore, content should be concept oriented
1067-
rather than focused on specific tasks, e.g.
1068-
1069-
Lines in Matplotlib
1070-
1071-
rather than *How do I make a squiggly yellow line?*
1072-
1073-
Audience: new Matplotlib users
1074-
------------------------------
1075-
1076-
The audience for the user guide are readers who are getting introduced to using Matplotlib
1077-
through the guide; therefore, the user guide should be written with the assumption that
1078-
the reader does not yet know what Matplotlib calls a given visualization task nor
1079-
how any task is accomplished in Matplotlib. For example, each document should first
1080-
introduce or define the object/module/concept that it is discussing and why it is
1081-
important for the reader. e.g.
1082-
1083-
The `~.Line2D` class is an abstraction of a line and the ``LineCollection`` class is
1084-
an abstraction of a set of lines. ``Line2D`` and ``LineCollection`` objects manage
1085-
the properties and behavior of almost every line in an image. This means that one way
1086-
to modify a line is to call methods on its underlying object.*
1087-
1088-
As the user guide is intended to be read in a somewhat linear fashion, it should be
1089-
written with the assumption that the reader has read previous sections and cross
1090-
reference to those sections when it is critical that the reader has read those sections.
1091-
1092-
1093-
Scope: Visualization using Matplotlib
1094-
-------------------------------------
1095-
1096-
Many concepts in Matplotlib assume a grounding in visualization, statistics, Python
1097-
programming, and other topics to understand how they work. These concepts should be
1098-
contextualized using common terminology, but the focus should not stray from the
1099-
Matplotlib topic, e.g.
1100-
1101-
``Line2D`` objects take as input a list of pairwise coordinates (x,y) and generates
1102-
line segments connecting each pair of points with the next pair in the list.
1103-
1104-
Here *pairwise coordinates* are not defined because it is a common term from math and
1105-
therefore defining it is out of scope. For some terms, it may also be appropriate to
1106-
link out to an explanation.
1107-
1108-
Strategy: Chunking and Scaffolding
1109-
----------------------------------
1110-
1111-
When possible, the material is introduced in tightly scoped sections that build on top
1112-
of each other, using teaching strategies called `chunking and scaffolding`_.
1113-
Chunking is aimed at reducing `cognitive load`_ by keeping the focus of each section
1114-
relatively small, and scaffolding lays out instructional material such that each section
1115-
builds on the previous one. The idea is to help the user develop a model of the concept
1116-
by first defining it and then illustrating how that understanding facilitates better use
1117-
of the library.
1118-
1119-
For example, here the line object is introduced, then there is one example of using a
1120-
method on the object. This primes the reader to better understand the example where the
1121-
two concepts are combined, and then there is a link out to further functionality::
1122-
1123-
For example, here the ``plot`` method returns a line object ``ln``::
1124-
1125-
ln, _ = plt.plot([1,2,3], color='blue')
1126-
1127-
One of the properties of a line is its color. It can be modified using the
1128-
``set_color`` method of ``Line2D``::
1129-
1130-
ln.set_color('orange')
1131-
1132-
As shown in the figure below, the line color resulting from this modification is
1133-
orange:
1134-
1135-
ln, _ = plt.plot([1,2,3], color='blue')
1136-
ln.set_color('orange')
1137-
1138-
For a full list of methods see `~.Line2D`
1139-
1140-
For some examples, it may be preferable to take the inverse approach: start with
1141-
the combined example and then unpack it into its pieces.
1142-
1143-
.. _`chunking and scaffolding`: https://www.tacoma.uw.edu/digital-learning/chunking-scaffolding-pacing
1144-
.. _`cognitive load`: https://carpentries.github.io/instructor-training/05-memory.html
1145-
11461048
Miscellaneous
11471049
=============
11481050

doc/devel/tag_guidelines.rst

Lines changed: 0 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -44,32 +44,3 @@ Note: Tagging organization aims to work for 80-90% of cases. Some examples fall
4444
How to tag?
4545
-----------
4646
Put each tag as a directive at the bottom of the page.
47-
48-
Related content
49-
---------------
50-
51-
What is a gallery example?
52-
^^^^^^^^^^^^^^^^^^^^^^^^^^
53-
54-
The gallery of examples contains visual demonstrations of matplotlib features. Gallery examples exist so that users can scan through visual examples.
55-
56-
Unlike tutorials or user guides, gallery examples teach by demonstration, rather than by explanation or instruction.
57-
58-
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.
59-
60-
Format
61-
^^^^^^
62-
63-
All :ref:`examples-index` should aim to follow the following format:
64-
65-
* Title: 1-6 words, descriptive of content
66-
* Subtitle: 10-50 words, action-oriented description of the example subject
67-
* Image: a clear demonstration of the subject, showing edge cases and different applications if possible
68-
* Code + Text (optional): code, commented as appropriate + written text to add context if necessary
69-
70-
Example:
71-
72-
The ``bbox_intersect`` gallery example demonstrates the point of visual examples:
73-
74-
* 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
75-
* https://matplotlib.org/devdocs/gallery/misc/bbox_intersect.html#sphx-glr-gallery-misc-bbox-intersect-py

0 commit comments

Comments
 (0)
0