From 06c8d4aa078de69474615c1656dc19e7cccdce78 Mon Sep 17 00:00:00 2001 From: David Stansby Date: Thu, 16 Nov 2017 18:41:28 +0000 Subject: [PATCH] WIP Update documentating guide Add link to numpydoc Add missing dash Fix build Get rid of extra bits Move setter/getter/kwarg section to near bottom More cleanup Remove sections covered in sphinx docs More small fixes Correct sgskip Update title More cleaning Move setters/getters/kwargs back Clarify examples/tutorials directories Fix code indentation Improve figure discussion Improve some headings Add intersphinx section --- doc/devel/documenting_mpl.rst | 451 ++++++++++++++-------------------- 1 file changed, 180 insertions(+), 271 deletions(-) diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst index dd23790654cb..c0222ffead54 100644 --- a/doc/devel/documenting_mpl.rst +++ b/doc/devel/documenting_mpl.rst @@ -1,8 +1,8 @@ .. _documenting-matplotlib: -=========================================== -Developer's tips for documenting Matplotlib -=========================================== +===================== +Writing documentation +===================== Getting started =============== @@ -11,9 +11,9 @@ Installing dependencies ----------------------- The documentation for Matplotlib is generated from reStructuredText using -the Sphinx_ documentation generation tool. There are several extra -requirements that are needed to build the documentation. They are listed in -:file:`doc-requirements.txt` as well as listed below: +the Sphinx_ documentation generation tool. There are several extra requirements +that are needed to build the documentation. They are listed in +:file:`doc-requirements.txt` and listed below: 1. Sphinx 1.3 or later (1.5.0 is not supported) 2. numpydoc 0.4 or later @@ -29,95 +29,177 @@ requirements that are needed to build the documentation. They are listed in * `Graphviz `_ is not a Python package, and needs to be installed separately. -General structure ------------------ +General file structure +---------------------- All documentation is built from the :file:`doc/` directory. This directory -contains both ``.rst`` files that contain pages in the documentation, -directories that contain more ``.rst`` files, and configuration files for -Sphinx_. +contains both ``.rst`` files that contain pages in the documentation and +configuration files for Sphinx_. + +The ``.rst`` files are kept in :file:`doc/users`, +:file:`doc/devel`, :file:`doc/api` and :file:`doc/faq`. The main entry point is +:file:`doc/index.rst`, which pulls in the :file:`index.rst` file for the users +guide, developers guide, api reference, and FAQs. The documentation suite is +built as a single document in order to make the most effective use of cross +referencing. .. note:: - An exception to this are the directories :file:`gallery` and + An exception to this are the directories :file:`examples` and :file:`tutorials`, which exist in the root directory. These contain Python files that are built by `Sphinx Gallery`_. When the docs are built, - directories of the same name will be generated inside of :file:`docs/`. The - generated directories :file:`docs/gallery` and :file:`docs/tutorials` can be - safely deleted. + the directories :file:`docs/gallery` and :file:`docs/tutorials` + are automatically generated. Do not edit the rst files in :file:docs/gallery + and :file:docs/tutorials, as they are rebuilt from the original sources in + the root directory. + + +Additional files can be added to the various guides by including their base +file name (the .rst extension is not necessary) in the table of contents. +It is also possible to include other documents through the use of an include +statement, such as:: + + .. include:: ../../TODO -The configuration file for Sphinx is :file:`doc/conf.py`. It controls which +The configuration file for Sphinx is :file:`doc/conf.py`. It controls which directories Sphinx parses, how the docs are built, and how the extensions are used. Building the docs ----------------- -The documentation sources are found in the :file:`doc/` directory in -the trunk. To build the users guide in html format, cd into -:file:`doc/` and do: +The documentation sources are found in the :file:`doc/` directory in the trunk. +To build the documentation in html format, cd into :file:`doc/` and run: .. code-block:: sh python make.py html -The list of comamnds and flags for ``make.py`` can be listed by running -``python make.py --help``. In particular, +The list of commands and flags for ``make.py`` can be listed by running +``python make.py --help``. In particular, -* ``python make.py clean`` will delete the built Sphinx files. Use this - command if you're getting strange errors about missing paths or broken links, +* ``python make.py clean`` will delete the built Sphinx files. Use this command + if you're getting strange errors about missing paths or broken links, particularly if you move files around. * ``python make.py latex`` builds a PDF of the documentation. * The ``--allowsphinxwarnings`` flag allows the docs to continue building even - if Sphinx throws a warning. This is useful for debugging and spot-checking + if Sphinx throws a warning. This is useful for debugging and spot-checking many warnings at once. +.. _formatting-mpl-docs: -Organization of Matplotlib's documentation -========================================== +Writing new documentation +========================= -The actual reStructured Text files are kept in :file:`doc/users`, -:file:`doc/devel`, :file:`doc/api` and :file:`doc/faq`. The main entry point is -:file:`doc/index.rst`, which pulls in the :file:`index.rst` file for the users -guide, developers guide, api reference, and faqs. The documentation suite is -built as a single document in order to make the most effective use of cross -referencing, we want to make navigating the Matplotlib documentation as easy as -possible. +Most documentation lives in "docstrings". These are comment blocks in source +code that explain how the code works. All new or edited docstrings should +conform to the numpydoc guidelines. These split the docstring into a number +of sections - see +https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt for more +details and a guide to how docstrings should be formatted. -Additional files can be added to the various guides by including their base -file name (the .rst extension is not necessary) in the table of contents. -It is also possible to include other documents through the use of an include -statement, such as:: +An example docstring looks like: - .. include:: ../../TODO +.. code-block:: python + + def hlines(self, y, xmin, xmax, colors='k', linestyles='solid', + label='', **kwargs): + """ + Plot horizontal lines at each *y* from *xmin* to *xmax*. + + Parameters + ---------- + y : scalar or sequence of scalar + y-indexes where to plot the lines. + + xmin, xmax : scalar or 1D array_like + Respective beginning and end of each line. If scalars are + provided, all lines will have same length. + + colors : array_like of colors, optional, default: 'k' + + linestyles : ['solid' | 'dashed' | 'dashdot' | 'dotted'], optional + + label : string, optional, default: '' + + Returns + ------- + lines : `~matplotlib.collections.LineCollection` + + Other Parameters + ---------------- + **kwargs : `~matplotlib.collections.LineCollection` properties. + + See also + -------- + vlines : vertical lines + axhline: horizontal line across the axes + """ -docstrings ----------- +The Sphinx website also contains plenty of documentation_ concerning ReST +markup and working with Sphinx in general. -In addition to the "narrative" documentation described above, -Matplotlib also defines its API reference documentation in docstrings. -For the most part, these are standard Python docstrings, but -Matplotlib also includes some features to better support documenting -getters and setters. +Linking to other code +--------------------- +To link to other methods, classes, or modules in Matplotlib you can encase +the name to refer to in back ticks, for example: +.. code-block:: python + + `~matplotlib.collections.LineCollection` + +It is also possible to add links to code in Python, Numpy, Scipy, or Pandas. +Sometimes it is tricky to get external Sphinx linking to work; to check that +a something exists to link to the following shell command outputs a list of all +objects that can be referenced (in this case for Numpy):: + + python -m sphinx.ext.intersphinx 'https://docs.scipy.org/doc/numpy/objects.inv' + + +Function arguments +------------------ +Function arguments and keywords within docstrings should be referred to using +the ``*emphasis*`` role. This will keep Matplotlib's documentation consistent +with Python's documentation: + +.. code-block:: rst + + Here is a description of *argument* + +Please do not use the ```default role```: + + +.. code-block:: rst + + Please do not describe `argument` like this. + +nor the ````literal```` role: + +.. code-block:: rst + + Please do not describe ``argument`` like this. + +Setters and getters +------------------- Matplotlib uses artist introspection of docstrings to support properties. All properties that you want to support through `~.pyplot.setp` and `~.pyplot.getp` should have a ``set_property`` and ``get_property`` method in -the `~.matplotlib.artist.Artist` class. Yes, this is not ideal given python -properties or enthought traits, but it is a historical legacy for now. The -setter methods use the docstring with the ACCEPTS token to indicate the type of -argument the method accepts. e.g., in `.Line2D`: +the `~.matplotlib.artist.Artist` class. The setter methods use the docstring +with the ACCEPTS token to indicate the type of argument the method accepts. +e.g., in `.Line2D`: .. code-block:: python - # in lines.py - def set_linestyle(self, linestyle): - """ - Set the linestyle of the line + # in lines.py + def set_linestyle(self, linestyle): + """ + Set the linestyle of the line - ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ] - """ + ACCEPTS: [ '-' | '--' | '-.' | ':' | 'steps' | 'None' | ' ' | '' ] + """ +Keyword arguments +----------------- Since Matplotlib uses a lot of pass-through ``kwargs``, e.g., in every function that creates a line (`~.pyplot.plot`, `~.pyplot.semilogx`, `~.pyplot.semilogy`, etc...), it can be difficult for the new user to know which ``kwargs`` are @@ -129,10 +211,10 @@ are: require multiple docstring edits. 2. as automated as possible so that as properties change, the docs - are updated automagically. + are updated automatically. The function `matplotlib.artist.kwdoc` and the decorator -`matplotlib.docstring.dedent_interpd` facilitate this. They combine python +`matplotlib.docstring.dedent_interpd` facilitate this. They combine Python string interpolation in the docstring with the Matplotlib artist introspection facility that underlies ``setp`` and ``getp``. The ``kwdoc`` function gives the list of properties as a docstring. In order to use this in another @@ -163,7 +245,6 @@ Then in any function accepting `~.Line2D` pass-through ``kwargs``, e.g., autoscaled; default True. See Axes.autoscale_view for more information """ - pass Note there is a problem for `~matplotlib.artist.Artist` ``__init__`` methods, e.g., `matplotlib.patches.Patch.__init__`, which supports ``Patch`` ``kwargs``, @@ -173,208 +254,41 @@ definition. There are some some manual hacks in this case, violating the "single entry point" requirement above -- see the ``docstring.interpd.update`` calls in `matplotlib.patches`. -.. _formatting-mpl-docs: - -Formatting -========== - -The Sphinx website contains plenty of documentation_ concerning ReST markup and -working with Sphinx in general. Here are a few additional things to keep in mind: - -* Please familiarize yourself with the Sphinx directives for `inline - markup`_. Matplotlib's documentation makes heavy use of cross-referencing and - other semantic markup. For example, when referring to external files, use the - ``:file:`` directive. - -* Function arguments and keywords should be referred to using the - ``*emphasis*`` role. This will keep Matplotlib's documentation consistent - with Python's documentation: - - .. code-block:: rst - - Here is a description of *argument* - - Please do not use the ```default role```: +Adding figures +============== +Figures in the documentation are automatically generated from scripts. +It is not necessary to explicitly save the figure from the script; this will be +done automatically when the docs are built to ensure that the code that is +included runs and produces the advertised figure. - .. code-block:: rst - - Please do not describe `argument` like this. - - nor the ````literal```` role: - - .. code-block:: rst - - Please do not describe ``argument`` like this. - -* Mathematical expressions can be rendered as png images in html, and in the - usual way by LaTeX. For example, - - .. code-block:: rst - - :math:`\sin(x_n^2)` - - yields :math:`\sin(x_n^2)`, and: - - .. code-block:: rst - - .. math:: - - \int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}} - - yields :math:`\int_{-\infty}^{\infty}\frac{e^{i\phi}}{1+x^2\frac{e^{i\phi}}{1+x^2}}`. - -* Interactive IPython sessions can be illustrated in the documentation using - the following directive: - - .. code-block:: rst - - .. sourcecode-block:: ipython - - In [69]: lines = plot([1,2,3]) - - which yields - - .. code-block:: ipython - - In [69]: lines = plot([1,2,3]) - -* Footnotes [#]_ can be added using ``[#]_``, followed later by: - - .. code-block:: rst - - .. rubric:: Footnotes - - .. [#] - - which yields - - .. rubric:: Footnotes - - .. [#] For example. - -* Use the *note* and *warning* directives, sparingly, to draw attention to - important comments: - - .. code-block:: rst - - .. note:: - Here is a note. - - .. warning:: - Here is a warning. - - yields: - - .. note:: - Here is a note. - - .. warning:: - Here is a warning. - -* Use the *deprecated* directive when appropriate: - - .. code-block:: rst - - .. deprecated:: 0.98 - This feature is obsolete, use something else. - - yields: - - .. deprecated:: 0.98 - This feature is obsolete, use something else. - -* Use the *versionadded* and *versionchanged* directives, which have similar - syntax to the *deprecated* role: - - .. code-block:: rst - - .. versionadded:: 0.98 - The transforms have been completely revamped. - - .. versionadded:: 0.98 - The transforms have been completely revamped. - -* Use the *seealso* directive, for example: - - .. code-block:: rst - - .. seealso:: - - Using ReST :ref:`emacs-helpers`: - One example - - A bit about :ref:`referring-to-mpl-docs`: - One more - - yields: - - .. seealso:: - - Using ResT :ref:`emacs-helpers`: - One example - - A bit about :ref:`referring-to-mpl-docs`: - One more - -* Please keep the :ref:`glossary` in mind when writing documentation. You can - create a references to a term in the glossary with the ``:term:`` role. - -* The autodoc extension will handle index entries for the API, but additional - entries in the index_ need to be explicitly added. - -* Keyword arguments should be described using a definition list. - - .. note:: - Matplotlib makes extensive use of keyword arguments as pass-through - arguments, there are a many cases where a table is used in place of a - definition list for autogenerated sections of docstrings. - -Figures -======= - -Dynamically generated figures ------------------------------ - -Figures can be automatically generated from scripts and included in -the docs. It is not necessary to explicitly save the figure in the -script, this will be done automatically at build time to ensure that -the code that is included runs and produces the advertised figure. - -The path should be relative to the ``doc`` directory. Any plots -specific to the documentation should be added to the ``doc/mpl_examples/pyplots`` -directory and committed to git. Plots from the ``examples`` directory -may be referenced through the symlink ``mpl_examples`` in the ``doc`` -directory, e.g.: +There are two options for where to put the code that generates a figure. If +you want to include a plot in the examples gallery, the code should be added to +the :file:`examples` directory. Plots from +the :file:`examples` directory can then be referenced through the symlink +``mpl_examples`` in the ``doc`` directory, e.g.: .. code-block:: rst - .. plot:: mpl_examples/pylab_examples/simple_plot.py + .. plot:: mpl_examples/lines_bars_and_markers/fill.py -The ``:scale:`` directive rescales the image to some percentage of the -original size, though we don't recommend using this in most cases -since it is probably better to choose the correct figure size and dpi -in Matplotlib and let it handle the scaling. +Alternatively the plotting code can be placed directly in the docstring. +To include plots directly in docstrings, see the following guide: Plot directive documentation -'''''''''''''''''''''''''''' +---------------------------- .. automodule:: matplotlib.sphinxext.plot_directive + :no-undoc-members: Examples -------- -The source of the files in the ``examples`` directory are -automatically included in the HTML docs. An image is generated and -included for all examples in the ``api`` and ``pylab_examples`` -directories. To exclude the example from having an image rendered, -insert the following special comment anywhere in the script: +The source of the files in the :file:`examples` directory are automatically run +and their output plots included in the documentation. To exclude an example +from having an plot generated insert "sgskip" somewhere in the filename. -.. code-block:: python - - # -*- noplot -*- - -Animations ----------- +Adding animations +================= We have a Matplotlib Google/Gmail account with username ``mplgithub`` which we used to setup the github account but can be used for other @@ -408,27 +322,26 @@ google docs to the mplgithub account. .. _referring-to-mpl-docs: -Referring to Matplotlib documents -================================= +Referring to data files +======================= -In the documentation, you may want to include to a document in the Matplotlib -sources, e.g., a license file or an image file from :file:`mpl-data`, refer to -it via a relative path from the document where the rst file resides, e.g., in -:file:`users/navigation_toolbar.rst`, we refer to the image icons with:: +In the documentation, you may want to include to a data file in the Matplotlib +sources, e.g., a license file or an image file from :file:`mpl-data`, refer to it via +a relative path from the document where the rst file resides, e.g., +in :file:`users/navigation_toolbar.rst`, you can refer to the image icons with:: .. image:: ../../lib/matplotlib/mpl-data/images/subplots.png -In the :file:`users` subdirectory, if I want to refer to a file in the -mpl-data directory, I use the symlink directory. For example, from -:file:`customizing.rst`:: +In the :file:`users` subdirectory, if you want to refer to a file in the +:file:`mpl-data` directory, you can use the symlink directory. For example, +from :file:`customizing.rst`:: .. literalinclude:: ../../lib/matplotlib/mpl-data/matplotlibrc -One exception to this is when referring to the examples dir. Relative -paths are extremely confusing in the sphinx plot extensions, so -without getting into the dirty details, it is easier to simply include -a symlink to the files at the top doc level directory. This way, API -documents like :meth:`matplotlib.pyplot.plot` can refer to the +One exception to this is when referring to the examples directory. Relative +paths are extremely confusing in the sphinx plot extensions, so it is easier +to simply include a symlink to the files at the top doc level directory. +This way, API documents like :meth:`matplotlib.pyplot.plot` can refer to the examples in a known location. In the top level :file:`doc` directory we have symlinks pointing to the @@ -445,10 +358,6 @@ So we can include plots from the examples dir using the symlink: .. plot:: mpl_examples/pylab_examples/simple_plot.py -We used to use a symlink for :file:`mpl-data` too, but the distro -becomes very large on platforms that do not support links (e.g., the font -files are duplicated and large) - .. _internal-section-refs: Internal section references @@ -468,7 +377,7 @@ and refer to it using the standard reference syntax: See :ref:`howto-webapp` Keep in mind that we may want to reorganize the contents later, so -let's avoid top level names in references like ``user`` or ``devel`` +please try to avoid top level names in references like ``user`` or ``devel`` or ``faq`` unless necessary, because for example the FAQ "what is a backend?" could later become part of the users guide, so the label: @@ -482,21 +391,21 @@ is better than: .. _faq-backend -In addition, since underscores are widely used by Sphinx itself, let's prefer +In addition, since underscores are widely used by Sphinx itself, please use hyphens to separate words. -Section names, etc. -=================== +Section name formatting +======================= For everything but top level chapters, please use ``Upper lower`` for section titles, e.g., ``Possible hangups`` rather than ``Possible Hangups`` -Inheritance diagrams -==================== +Generating inheritance diagrams +=============================== Class inheritance diagrams can be generated with the -``inheritance-diagram`` directive. To use it, you provide the +``inheritance-diagram`` directive. To use it, provide the directive with a number of class or module names (separated by whitespace). If a module name is provided, all classes in that module will be used. All of the ancestors of these classes will be included 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