From a9fce7fc796227e8aa16188602b79ae518b7e246 Mon Sep 17 00:00:00 2001 From: hannah Date: Mon, 15 Jul 2024 00:58:58 -0400 Subject: [PATCH] reorged doc docs to have common prefix and seperate doc build page --- doc/devel/contribute.rst | 7 +- doc/devel/development_workflow.rst | 2 +- doc/devel/document_build.rst | 124 +++++++++++++++++ .../{document.rst => document_format.rst} | 128 +----------------- .../{style_guide.rst => document_style.rst} | 10 +- .../{tag_guidelines.rst => document_tag.rst} | 8 +- ...glossary.rst => document_tag_glossary.rst} | 4 + doc/devel/index.rst | 7 +- 8 files changed, 156 insertions(+), 134 deletions(-) create mode 100644 doc/devel/document_build.rst rename doc/devel/{document.rst => document_format.rst} (90%) rename doc/devel/{style_guide.rst => document_style.rst} (99%) rename doc/devel/{tag_guidelines.rst => document_tag.rst} (92%) rename doc/devel/{tag_glossary.rst => document_tag_glossary.rst} (99%) diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst index 558e19790d82..92fafb95b3ec 100644 --- a/doc/devel/contribute.rst +++ b/doc/devel/contribute.rst @@ -137,9 +137,10 @@ Other documentation is generated from the following external sources: Instructions and guidelines for contributing documentation are found in: -* :doc:`document` -* :doc:`style_guide` -* :doc:`tag_guidelines` +* :doc:`document_build` +* :doc:`document_format` +* :doc:`document_style` +* :doc:`document_tag` Documentation is contributed through pull requests, so we recommend that you start at :ref:`how-to-pull-request`. If that feels intimidating, we encourage you to diff --git a/doc/devel/development_workflow.rst b/doc/devel/development_workflow.rst index d92d387152ba..9aadeec4e98e 100644 --- a/doc/devel/development_workflow.rst +++ b/doc/devel/development_workflow.rst @@ -157,7 +157,7 @@ Check that your change does what you intend. For code changes: For documentation changes, build the documentation locally to check that it renders how you intended and that any new links work correctly. See -:ref:`build_docs`. +:ref:`document-build`. This is also a good time to look through the :ref:`pr-author-guidelines` and address as many of the relevant points as you can. diff --git a/doc/devel/document_build.rst b/doc/devel/document_build.rst new file mode 100644 index 000000000000..d4a57ca491c5 --- /dev/null +++ b/doc/devel/document_build.rst @@ -0,0 +1,124 @@ +.. redirect-from:: /devel/document + +.. _documenting-matplotlib: +.. _document-build: + +******************* +Build Documentation +******************* + +All documentation is built from the :file:`doc/`. The :file:`doc/` +directory contains configuration files for Sphinx and reStructuredText +(ReST_; ``.rst``) files that are rendered to documentation pages. + +General file structure +====================== +Documentation is created in three ways. First, API documentation +(:file:`doc/api`) is created by Sphinx_ from +the docstrings of the classes in the Matplotlib library. Except for +:file:`doc/api/api_changes/`, ``.rst`` files in :file:`doc/api` are created +when the documentation is built. See :ref:`writing-docstrings` below. + +Second, our example pages, tutorials, and some of the narrative documentation +are created by `Sphinx Gallery`_. Sphinx Gallery converts example Python files +to ``*.rst`` files with the result of Matplotlib plot calls as embedded images. +See :ref:`writing-examples-and-tutorials` below. + +Third, Matplotlib has narrative docs written in ReST_ in subdirectories of +:file:`doc/users/`. If you would like to add new documentation that is suited +to an ``.rst`` file rather than a gallery or tutorial example, choose an +appropriate subdirectory to put it in, and add the file to the table of +contents of :file:`index.rst` of the subdirectory. See +:ref:`writing-rest-pages` below. + +.. note:: + + Don't directly edit the ``.rst`` files in :file:`doc/plot_types`, + :file:`doc/gallery`, :file:`doc/tutorials`, and :file:`doc/api` + (excepting :file:`doc/api/api_changes/`). Sphinx_ regenerates + files in these directories when building documentation. + +Set up the build +================ + +The documentation for Matplotlib is generated from reStructuredText (ReST_) +using the Sphinx_ documentation generation tool. + +To build the documentation you will need to +:ref:`set up Matplotlib for development `. Note in +particular the :ref:`additional dependencies ` required to +build the documentation. + +Build the docs +============== + +The documentation sources are found in the :file:`doc/` directory. +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. To build the documentation in html format, cd into :file:`doc/` and run: + +.. code-block:: sh + + make html + +.. note:: + + Since the documentation is very large, the first build may take 10-20 minutes, + depending on your machine. Subsequent builds will be faster. + +Other useful invocations include + +.. code-block:: sh + + # Build the html documentation, but skip generation of the gallery images to + # save time. + make html-noplot + + # Build the html documentation, but skip specific subdirectories. If a gallery + # directory is skipped, the gallery images are not generated. The first + # time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited + # to add or remove subdirectories + make html-skip-subdirs + + # Delete built files. May help if you get errors about missing paths or + # broken links. + make clean + + # Build pdf docs. + make latexpdf + +The ``SPHINXOPTS`` variable is set to ``-W --keep-going`` by default to build +the complete docs but exit with exit status 1 if there are warnings. To unset +it, use + +.. code-block:: sh + + make SPHINXOPTS= html + +You can use the ``O`` variable to set additional options: + +* ``make O=-j4 html`` runs a parallel build with 4 processes. +* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution. + +Multiple options can be combined, e.g. ``make O='-j4 -Dplot_formats=png:100' +html``. + +On Windows, set the options as environment variables, e.g.: + +.. code-block:: bat + + set SPHINXOPTS= & set O=-j4 -Dplot_formats=png:100 & make html + +Show locally built docs +======================= + +The built docs are available in the folder :file:`build/html`. A shortcut +for opening them in your default browser is: + +.. code-block:: sh + + make show + +.. _ReST: https://docutils.sourceforge.io/rst.html +.. _Sphinx: http://www.sphinx-doc.org +.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/ diff --git a/doc/devel/document.rst b/doc/devel/document_format.rst similarity index 90% rename from doc/devel/document.rst rename to doc/devel/document_format.rst index d40d281f8bb9..2fb6858debb3 100644 --- a/doc/devel/document.rst +++ b/doc/devel/document_format.rst @@ -1,128 +1,11 @@ .. redirect-from:: /devel/documenting_mpl -.. _documenting-matplotlib: -=================== -Write documentation -=================== - -Getting started -=============== - -General file structure ----------------------- - -All documentation is built from the :file:`doc/`. The :file:`doc/` -directory contains configuration files for Sphinx and reStructuredText -(ReST_; ``.rst``) files that are rendered to documentation pages. - -Documentation is created in three ways. First, API documentation -(:file:`doc/api`) is created by Sphinx_ from -the docstrings of the classes in the Matplotlib library. Except for -:file:`doc/api/api_changes/`, ``.rst`` files in :file:`doc/api` are created -when the documentation is built. See :ref:`writing-docstrings` below. - -Second, our example pages, tutorials, and some of the narrative documentation -are created by `Sphinx Gallery`_. Sphinx Gallery converts example Python files -to ``*.rst`` files with the result of Matplotlib plot calls as embedded images. -See :ref:`writing-examples-and-tutorials` below. - -Third, Matplotlib has narrative docs written in ReST_ in subdirectories of -:file:`doc/users/`. If you would like to add new documentation that is suited -to an ``.rst`` file rather than a gallery or tutorial example, choose an -appropriate subdirectory to put it in, and add the file to the table of -contents of :file:`index.rst` of the subdirectory. See -:ref:`writing-rest-pages` below. - -.. note:: - - Don't directly edit the ``.rst`` files in :file:`doc/plot_types`, - :file:`doc/gallery`, :file:`doc/tutorials`, and :file:`doc/api` - (excepting :file:`doc/api/api_changes/`). Sphinx_ regenerates - files in these directories when building documentation. - -Set up the build ----------------- - -The documentation for Matplotlib is generated from reStructuredText (ReST_) -using the Sphinx_ documentation generation tool. - -To build the documentation you will need to -:ref:`set up Matplotlib for development `. Note in -particular the :ref:`additional dependencies ` required to -build the documentation. - -.. _build_docs: - -Build the docs --------------- - -The documentation sources are found in the :file:`doc/` directory. -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. To build the documentation in html format, cd into :file:`doc/` and run: - -.. code-block:: sh - - make html - -.. note:: +.. _document-format: - Since the documentation is very large, the first build may take 10-20 minutes, - depending on your machine. Subsequent builds will be faster. - -Other useful invocations include - -.. code-block:: sh - - # Build the html documentation, but skip generation of the gallery images to - # save time. - make html-noplot - - # Build the html documentation, but skip specific subdirectories. If a gallery - # directory is skipped, the gallery images are not generated. The first - # time this is run, it creates ``.mpl_skip_subdirs.yaml`` which can be edited - # to add or remove subdirectories - make html-skip-subdirs - - # Delete built files. May help if you get errors about missing paths or - # broken links. - make clean - - # Build pdf docs. - make latexpdf - -The ``SPHINXOPTS`` variable is set to ``-W --keep-going`` by default to build -the complete docs but exit with exit status 1 if there are warnings. To unset -it, use - -.. code-block:: sh - - make SPHINXOPTS= html - -You can use the ``O`` variable to set additional options: - -* ``make O=-j4 html`` runs a parallel build with 4 processes. -* ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution. - -Multiple options can be combined, e.g. ``make O='-j4 -Dplot_formats=png:100' -html``. - -On Windows, set the options as environment variables, e.g.: - -.. code-block:: bat - - set SPHINXOPTS= & set O=-j4 -Dplot_formats=png:100 & make html - -Show locally built docs ------------------------ - -The built docs are available in the folder :file:`build/html`. A shortcut -for opening them in your default browser is: - -.. code-block:: sh - - make show +******************* +Write documentation +******************* .. _writing-rest-pages: @@ -1189,11 +1072,12 @@ Documentation page analytics are available at https://views.scientific-python.org/matplotlib.org. + .. _ReST: https://docutils.sourceforge.io/rst.html .. _Sphinx: http://www.sphinx-doc.org +.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/ .. _documentation: https://www.sphinx-doc.org/en/master/contents.html .. _index: http://www.sphinx-doc.org/markup/para.html#index-generating-markup -.. _`Sphinx Gallery`: https://sphinx-gallery.readthedocs.io/en/latest/ .. _references: https://www.sphinx-doc.org/en/stable/usage/restructuredtext/roles.html .. _`numpydoc docstring guide`: https://numpydoc.readthedocs.io/en/latest/format.html .. _`Manually passing files`: https://sphinx-gallery.github.io/stable/configuration.html#manually-passing-files diff --git a/doc/devel/style_guide.rst b/doc/devel/document_style.rst similarity index 99% rename from doc/devel/style_guide.rst rename to doc/devel/document_style.rst index e35112a65e42..121b68b11688 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/document_style.rst @@ -1,7 +1,10 @@ +.. redirect-from:: /devel/style_guide -========================= -Documentation style guide -========================= +.. _document_style: + +*********** +Style guide +*********** This guide contains best practices for the language and formatting of Matplotlib documentation. @@ -410,6 +413,7 @@ This style guide is not a comprehensive standard. For a more thorough reference of how to contribute to documentation, see the links below. These resources contain common best practices for writing documentation. + * `Python Developer's Guide `_ * `Google Developer Style Guide `_ * `IBM Style Guide `_ diff --git a/doc/devel/tag_guidelines.rst b/doc/devel/document_tag.rst similarity index 92% rename from doc/devel/tag_guidelines.rst rename to doc/devel/document_tag.rst index 2c80065982bc..09456ccf2a70 100644 --- a/doc/devel/tag_guidelines.rst +++ b/doc/devel/document_tag.rst @@ -1,3 +1,7 @@ +.. redirect-from:: /devel/tag_guidelines + +.. _document-tag-guidelines: + Tagging guidelines ================== @@ -50,10 +54,10 @@ title or the scope of the example. .. toctree:: :maxdepth: 2 - tag_glossary + document_tag_glossary +++ - See :doc:`Tag Glossary ` for a complete list + See :ref:`Tag Glossary ` for a complete list Proposing new tags ------------------ diff --git a/doc/devel/tag_glossary.rst b/doc/devel/document_tag_glossary.rst similarity index 99% rename from doc/devel/tag_glossary.rst rename to doc/devel/document_tag_glossary.rst index b3d0ec2bcbda..223b40435290 100644 --- a/doc/devel/tag_glossary.rst +++ b/doc/devel/document_tag_glossary.rst @@ -1,3 +1,7 @@ +.. redirect-from:: /devel/tag_glossary + +.. _document-tag-glossary: + Tag Glossary ============ diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 4c71027c75ba..a6c7d5c55d16 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -220,9 +220,10 @@ manage, or release manage, these guidelines describe how our current process wor .. toctree:: :maxdepth: 1 - document - style_guide - tag_guidelines + document_build + document_format + document_style + document_tag .. grid-item-card:: :shadow: none