Cleanup documentation in preparation for sphinx-doc/sphinx#10807

[asmeurer]

This upstream Sphinx PR will make each function, class, and method docstring appear in the table of contents (i.e., in the right sidebar). This means that headers like

sympify
^^^^^^^
.. autofunction:: sympify

are now redundant.

This can be merged before the upstream Sphinx PR is merged, however, until a Sphinx release is made with it, those pages will not have headers for the functions. However, the use of the above one-header-per-function style was done very inconsistently throughout the reference pages.

This PR also

• Changes all index.rst pages to use :titlesonly: instead of :maxdepth:. This makes the table of contents pages only show the table of contents for actual pages. With each function included in the ToC, showing them all on the index page made the table of contents quite large in many cases.

  These index pages are still mostly useless, especially given the left sidebar. I leave it to a future PR to either do something better with them or remove them entirely. This is related to Clean up some of the layout in the docs #23333.

• I have split the mechancs, vector, and physics vector API toc into separate index pages. This does not affect the URLs of the pages themselves (the API pages were already in separate api/ subdirectories), but it does make the left sidebar put these API pages under a separate foldable API heading.

• A few very minor cleanups. I have left most things intact they way they were, even in instances where things could clearly be improved.

References to other Issues or PRs

Fixes #23332.

Brief description of what is fixed or changed

Other comments

It's hard to keep this many changes up with merge conflicts, so I would like for this to be merged sooner rather than later.

Release Notes

• other
  • The documentation now lists each function, class, and method in the right sidebar.

[sympy-bot]

✅

Hi, I am the SymPy bot (v167). I'm here to help you write a release notes entry. Please read the guide on how to write release notes.

Your release notes are in good order.

Here is what the release notes will look like:

• other
  • The documentation now lists each function, class, and method in the right sidebar. (#24050 by @asmeurer)

This will be added to https://github.com/sympy/sympy/wiki/Release-Notes-for-1.12.

Click here to see the pull request description that was parsed.

This upstream Sphinx PR will make each function, class, and method docstring appear in the table of contents (i.e., in the right sidebar). This means that headers like

    sympify
    ^^^^^^^
    .. autofunction:: sympify

are now redundant.

This can be merged before the upstream Sphinx PR is merged, however, until a Sphinx release is made with it, those pages will not have headers for the functions. However, the use of the above one-header-per-function style was done very inconsistently throughout the reference pages.

This PR also

- Changes all index.rst pages to use :titlesonly: instead of :maxdepth:. This makes the table of contents pages only show the table of contents for actual pages. With each function included in the ToC, showing them all on the index page made the table of contents quite large in many cases.

  These index pages are still mostly useless, especially given the left sidebar. I leave it to a future PR to either do something better with them or remove them entirely. This is related to #23333.

- I have split the mechancs, vector, and physics vector API toc into separate index pages. This does not affect the URLs of the pages themselves (the API pages were already in separate api/ subdirectories), but it does make the left sidebar put these API pages under a separate foldable API heading.

- A few very minor cleanups. I have left most things intact they way they were, even in instances where things could clearly be improved.


<!-- Your title above should be a short description of what
was changed. Do not include the issue number in the title. -->

#### References to other Issues or PRs
<!-- If this pull request fixes an issue, write "Fixes #NNNN" in that exact
format, e.g. "Fixes #1234" (see
https://tinyurl.com/auto-closing for more information). Also, please
write a comment on that issue linking back to this pull request once it is
open. -->

Fixes #23332.


#### Brief description of what is fixed or changed


#### Other comments

It's hard to keep this many changes up with merge conflicts, so I would like for this to be merged sooner rather than later. 

#### Release Notes

<!-- Write the release notes for this release below between the BEGIN and END
statements. The basic format is a bulleted list with the name of the subpackage
and the release note for this PR. For example:

* solvers
  * Added a new solver for logarithmic equations.

* functions
  * Fixed a bug with log of integers.

or if no release note(s) should be included use:

NO ENTRY

See https://github.com/sympy/sympy/wiki/Writing-Release-Notes for more
information on how to write release notes. The bot will check your release
notes automatically to see if they are formatted correctly. -->

<!-- BEGIN RELEASE NOTES -->
- other
  - The documentation now lists each function, class, and method in the right sidebar. 
<!-- END RELEASE NOTES -->

Update

The release notes on the wiki have been updated.

[sympy-bot]

🟠

Hi, I am the SymPy bot (v167). I've noticed that some of your commits add or delete files. Since this is sometimes done unintentionally, I wanted to alert you about it.

This is an experimental feature of SymPy Bot. If you have any feedback on it, please comment at sympy/sympy-bot#75.

The following commits add new files:

• f7cf470:
  • doc/src/modules/physics/mechanics/api/index.rst
  • doc/src/modules/physics/vector/api/index.rst
  • doc/src/modules/vector/api/index.rst

If these files were added/deleted on purpose, you can ignore this message.

[asmeurer]

To see what this will look like, you'll need to build the docs against sphinx-doc/sphinx#10807. Here is an example of will look like. Note the headers in the right sidebar.

Before

After

[github-actions]

Benchmark results from GitHub Actions

Lower numbers are good, higher numbers are bad. A ratio less than 1
means a speed up and greater than 1 means a slowdown. Green lines
beginning with + are slowdowns (the PR is slower then master or
master is slower than the previous release). Red lines beginning
with - are speedups.

Significantly changed benchmark results (PR vs master)

Significantly changed benchmark results (master vs previous release)

       before           after         ratio
     [41d90958]       [870bd54a]
     <sympy-1.11.1^0>                 
-        1.18±0ms          756±3μs     0.64  solve.TimeSparseSystem.time_linear_eq_to_matrix(10)
-     3.43±0.03ms         1.40±0ms     0.41  solve.TimeSparseSystem.time_linear_eq_to_matrix(20)
-     6.84±0.02ms      2.05±0.01ms     0.30  solve.TimeSparseSystem.time_linear_eq_to_matrix(30)

Full benchmark results can be found as artifacts in GitHub Actions
(click on checks at the top of the PR).

[asmeurer]

A version of Sphinx with this enabled will be released very soon:

sphinx-doc/sphinx#10807 (comment)

P.S. Assuming it's merged, how long until we'll see it published to PyPI? (looks like this replaces workarounds on a lot of our projects)

5.2 should be released within the month. I want to clear all items from the milestone before release.

A

[asmeurer]

Sphinx 5.2.0 has been released with this change. Compare the right sidebar on https://docs.sympy.org/dev/modules/ntheory.html with this PR. Any objections to merging this?

[asmeurer]

The dev docs are already being built with 5.2.0, which is leading to duplicate headers (see e.g., the sidebar at https://docs.sympy.org/dev/modules/core.html#eq).

[asmeurer]

Another merge conflict. I think I'm just going to self-merge this. If someone wants to review feel free to cancel it.