Modernize sphinx

[guyer]

Clean up legacy Sphinx hacks and resolve longstanding warnings.

Support use of NISTtheDocs2Death to put documentation on https://pages.nist.gov/fipy.

Previous configuration went to great lengths to "see" things outside documentation directory, which is not the intended design of sphinx. Using autodoc instead of autosummary simplifies things considerably.

• [x] Search box does not appear (Fixes #865)
• [x] Fixes #673

Test failures are only nix.

[!NOTE] The remaining warning is because mayavi isn't installed.

Attempting to use docs/environment.yml causes a 30 min delay.

Adding mayavi to docs/requirements.txt slows down installation by 10 min and doesn't resolve the error.

(petsc was fixed with autodoc_mock_imports, but attempting to add petsc4py to docs/requirements.txt fails when trying to build wheel.)

[guyer]

See https://pages.nist.gov/fipy/en/modernize_sphinx for build results

[wd15]

I can't find any issues when randomly checking the changes and the rendered version on pages.nist.gov. I'll try and fix the nix tests at some point.

[guyer]

I can't find any issues when randomly checking the changes and the rendered version on pages.nist.gov. I'll try and fix the nix tests at some point.

Much obliged @wd15

[guyer]

Ah-Ha! I found the typo!

Curses!

[tkphd]

The PDF docs build, but there are a lot of empty "chapters" for Examples:

The links in the chapter TOCs take the reader to the fipy Package Documentation examples section, some 800 pages further into the manual.

[guyer]

The PDF docs build, but there are a lot of empty "chapters" for Examples:

The links in the chapter TOCs take the reader to the fipy Package Documentation examples section, some 800 pages further into the manual.

Well, they're not empty; they're just lists of links. It's not feasible to render the examples twice, nor am I sure it would be a good idea to do so.

The point of the "II. Examples" part is to give a curated list of examples that will help teach users how to use FiPy. The point of "III. fipy Package Documentation > examples" is to provide a complete API listing of all of the examples that are used to test the higher functionality of FiPy.

The way we used to do it, with just the curated examples and no API listing of all examples generated lots of errors and warnings when I started using sphinx "properly".

Is there a better way to present this? If I incorporated "II. Examples" as a chapter in "I. Introduction", then the sections would still be "empty", but they wouldn't be chapters. Would that be better?

Frankly, I'm starting to wonder if a 1200 page PDF isn't just useless and stupid.

[tkphd]

Fair. Perhaps include verbiage in II reflecting the fact that these are lists of links, deliberately devoid of content?

[guyer]

PETSc breakages linux-py3k-petsc, linux-py3k-petsc-parallel, macos-py3k-petsc, macos-py3k-petsc-parallel unrelated to this PR. They correspond to PETSc 3.20.0, (released 2023-09-28, conda-forge petsc4py feedstock updated 2023-10-04). Previous PETSc 3.18.4 worked fine.