applying toc styling to remove nesting

story645 · story645 · commit 2abd354037a6 · 2024-07-17T23:54:26.000-04:00
updating to sphinx7.4.0 to use new toctree :class: attribute
change "new contributors" section title to "contributing guide"
add copy to anchor each section of devel/index
small doc cleanups based on above
diff --git a/doc/devel/contribute.rst b/doc/devel/contribute.rst
@@ -2,9 +2,10 @@
 
 .. _contributing:
 
-**********
-Contribute
-**********
+******************
+Contributing guide
+******************
+
 
 You've discovered a bug or something else you want to change
 in Matplotlib — excellent!
@@ -13,10 +14,6 @@ You've worked out a way to fix it — even better!
 
 You want to tell us about it — best of all!
 
-This project is a community effort, and everyone is welcome to contribute. Everyone
-within the community is expected to abide by our `code of conduct
-<https://github.com/matplotlib/matplotlib/blob/main/CODE_OF_CONDUCT.md>`_.
-
 Below, you can find a number of ways to contribute, and how to connect with the
 Matplotlib community.
 
diff --git a/doc/devel/index.rst b/doc/devel/index.rst
@@ -16,13 +16,26 @@ Contribute
 :octicon:`heart;1em;sd-text-info` Thank you for your interest in helping to improve
 Matplotlib! :octicon:`heart;1em;sd-text-info`
 
-There are various ways to contribute: optimizing and refactoring code, detailing
-unclear documentation and writing new examples, helping the community, reporting
-and fixing bugs and requesting and implementing new features...
+This project is a community effort, and everyone is welcome to contribute. Everyone
+within the community is expected to abide by our :ref:`code of conduct <code_of_conduct>`.
+
+There are various ways to contribute, such as optimizing and refactoring code,
+detailing unclear documentation and writing new examples, helping the community,
+reporting and fixing bugs, requesting and implementing new features...
 
 .. _submitting-a-bug-report:
 .. _request-a-new-feature:
 
+Issue tracker
+=============
+The `issue tracker <https://github.com/matplotlib/matplotlib/issues>`_ serves as the
+centralized location for making feature requests, reporting bugs, identifying major
+projects to work on, and discussing priorities.
+
+We have preloaded the issue creation page with markdown forms requesting the information
+we need to triage issues and we welcome you to add any additional information or
+context that may be necessary for resolving the issue:
+
 .. grid:: 1 1 2 2
 
    .. grid-item-card::
@@ -31,9 +44,7 @@ and fixing bugs and requesting and implementing new features...
       :octicon:`bug;1em;sd-text-info` **Submit a bug report**
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-      We have preloaded the issue creation page with a Markdown form that you can
-      use to provide relevant context. Thank you for your help in keeping bug reports
-      complete, targeted and descriptive.
+      Thank you for your help in keeping bug reports complete, targeted and descriptive.
 
       .. button-link:: https://github.com/matplotlib/matplotlib/issues/new/choose
             :expand:
@@ -47,27 +58,24 @@ and fixing bugs and requesting and implementing new features...
       :octicon:`light-bulb;1em;sd-text-info` **Request a new feature**
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-      We will give feedback on the feature proposal. Since
-      Matplotlib is an open source project with limited resources, we encourage
-      users to then also :ref:`participate in the implementation <contribute_code>`.
+      Thank you for your help in keeping feature requests well defined and tightly scoped.
 
       .. button-link:: https://github.com/matplotlib/matplotlib/issues/new/choose
          :expand:
          :color: primary
 
          Request a feature
 
+Since Matplotlib is an open source project with limited resources, we encourage users
+to then also :ref:`participate <contribute_code>` in fixing bugs and implementing new
+features.
+
+Contributing guide
+==================
 
 We welcome you to get more involved with the Matplotlib project! If you are new
 to contributing, we recommend that you first read our
-:ref:`contributing guide<contributing>`. If you are contributing code or
-documentation, please follow our guides for setting up and managing a
-:ref:`development environment and workflow<development_environment>`.
-For code, documentation, or triage, please follow the corresponding
-:ref:`contribution guidelines <contribution_guideline>`.
-
-New contributors
-================
+:ref:`contributing guide<contributing>`:
 
 .. toctree::
    :hidden:
@@ -115,13 +123,13 @@ New contributors
 
             :octicon:`globe;1em;sd-text-info` Build community
 
-
-
-
 .. _development_environment:
 
-Development environment
-=======================
+Development workflow
+====================
+
+If you are contributing code or documentation, please follow our guide for setting up
+and managing a development environment and workflow:
 
 .. grid:: 1 1 2 2
 
@@ -159,6 +167,11 @@ Development environment
 Policies and guidelines
 =======================
 
+These policies and guidelines help us maintain consistency in the various types
+of maintenance work. If you are writing code or documentation, following these policies
+helps maintainers more easily review your work. If you are helping triage, community
+manage, or release manage, these guidelines describe how our current process works.
+
 .. grid:: 1 1 2 2
    :class-row: sf-fs-1
    :gutter: 2
diff --git a/doc/devel/tag_guidelines.rst b/doc/devel/tag_guidelines.rst
@@ -45,10 +45,10 @@ title or the scope of the example.
 
     **Tag Categories**
     ^^^
-    .. rst-class:: section-toc
 
     .. toctree::
         :maxdepth: 2
+        :class: section-toc
 
         tag_glossary
 
diff --git a/doc/index.rst b/doc/index.rst
@@ -32,6 +32,7 @@ Install
     .. tab-item:: other
 
         .. toctree::
+            :class: section-toc
             :maxdepth: 2
 
             install/index
@@ -107,6 +108,7 @@ Community
     .. grid-item::
 
         .. toctree::
+            :class: section-toc
             :maxdepth: 2
 
             users/resources/index.rst
@@ -144,12 +146,12 @@ Contribute
 
     .. grid-item::
 
-        Matplotlib is a community project maintained for and by its users.
-
-        There are many ways you can help!
+        Matplotlib is a community project maintained for and by its users. See
+        :ref:`developers-guide-index` for the many ways you can help!
 
     .. grid-item::
         .. toctree::
+            :class: section-toc
             :maxdepth: 2
 
             devel/index.rst
@@ -168,8 +170,8 @@ About us
         and hard things possible.
 
     .. grid-item::
-
         .. toctree::
+            :class: section-toc
             :maxdepth: 2
 
             project/index.rst
diff --git a/environment.yml b/environment.yml
@@ -37,7 +37,7 @@ dependencies:
   - packaging>=20
   - pydata-sphinx-theme~=0.15.0
   - pyyaml
-  - sphinx>=3.0.0,!=6.1.2
+  - sphinx>=7.4.0,!=6.1.2
   - sphinx-copybutton
   - sphinx-gallery>=0.12.0
   - sphinx-design
diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt
@@ -7,7 +7,7 @@
 # Install the documentation requirements with:
 #     pip install -r requirements/doc/doc-requirements.txt
 #
-sphinx>=3.0.0,!=6.1.2
+sphinx>=7.4.0,!=6.1.2
 colorspacious
 ipython
 ipywidgets

Original file line number	Diff line number	Diff line change
`@@ -7,7 +7,7 @@`
`7`	`7`	`# Install the documentation requirements with:`
`8`	`8`	`# pip install -r requirements/doc/doc-requirements.txt`
`9`	`9`	`#`
`10`		`-sphinx>=3.0.0,!=6.1.2`
	`10`	`+sphinx>=7.4.0,!=6.1.2`
`11`	`11`	`colorspacious`
`12`	`12`	`ipython`
`13`	`13`	`ipywidgets`