DOCS: Website documentation about solvers is wildly out of date

[JDBetteridge]

Describe the issue
I can't remember when the default solver option for LVP became LU, but it was a long time ago!

Where to find
Where to find the error or where documentation should be:
(website/github/docstrings/etc.)

• Default solver options

Additional info
Add any other information here.

[tcalderon-space]

Hello, I am new to this community. I am interested in participating in the community by helping out with the issues. I would like to contribute with this issue here.

Would the correct adjustment for the solver option be something like https://www.firedrakeproject.org/solving-interface.html under "Recursive Fieldsplit" section?

The update you are requesting is to update the pc_type parameter to "LU" on the page given. Is that correct? I think the documentation might have already been updated...

[JDBetteridge]

Not quite, the bit that needs updating is in the default solver options section here:
https://www.firedrakeproject.org/solving-interface.html#default-solver-options
The introductory paragraph here, is also wrong:
https://www.firedrakeproject.org/solving-interface.html#linear-solver-options

The relevant file that needs changing is here:
https://github.com/firedrakeproject/firedrake/blob/master/docs/source/solving-interface.rst

You can find the specification for default solver options here:
https://github.com/firedrakeproject/firedrake/blob/master/firedrake/petsc.py#L449-L452
Here:
https://github.com/firedrakeproject/firedrake/blob/master/firedrake/variational_solver.py#L134-L143
And here:
https://github.com/firedrakeproject/firedrake/blob/master/firedrake/variational_solver.py#L417-L420

It would be very cool if we could have the documentation automatically generated so that if this ever changes again there is a single source of truth, but in the short term correcting this mistake would be sufficient.

In anticipation of your future PR, thanks! 🙂

[connorjward]

Note that this issue is more or less a duplicate of #4065 and so both can be closed at once.

It isn't too difficult to automatically generate the text to have a single source of truth. It is what we do here for example (injected into the docs here). But as @JDBetteridge says that isn't essential.

[tcalderon-space]

Hello,

I am currently working on updating the first request. I wanted to make sure the updates I made were correct before doing a pull request, however, when i use "make html" I run into an error with Sphinx. I was wondering if there is another way to call "make html" without using sphinxcontrib.inkscapeconverter... I tried to installed this package but I think it may be out of date..

Here is my error below..

(venv-firedrake) tcalder@tianna-laptop:~/venv-firedrake/firedrake/docs$ make html
install -d source/demos
cp ../demos//.rst ../demos/demo_references.bib ../demos//.geo ../demos//.msh ../demos//.png source/demos
for file in source/demos/.py.rst; do pylit $file; done
Output written to 'source/demos/DG_advection.py'
Output written to 'source/demos/benney_luke.py'
Output written to 'source/demos/burgers.py'
Output written to 'source/demos/camassaholm.py'
Output written to 'source/demos/extruded_continuity.py'
Output written to 'source/demos/full_waveform_inversion.py'
Output written to 'source/demos/geometric_multigrid.py'
Output written to 'source/demos/helmholtz.py'
Output written to 'source/demos/higher_order_mass_lumping.py'
Output written to 'source/demos/immersed_fem.py'
Output written to 'source/demos/linear_fluid_structure_interaction.py'
Output written to 'source/demos/linear_wave_equation.py'
Output written to 'source/demos/ma-demo.py'
Output written to 'source/demos/navier_stokes.py'
Output written to 'source/demos/netgen_mesh.py'
Output written to 'source/demos/parprint.py'
Output written to 'source/demos/poisson.py'
Output written to 'source/demos/poisson_mixed.py'
Output written to 'source/demos/qg_1layer_wave.py'
Output written to 'source/demos/qg_winddrivengyre.py'
Output written to 'source/demos/qgbasinmodes.py'
Output written to 'source/demos/rayleigh-benard.py'
Output written to 'source/demos/saddle_point_systems.py'
Output written to 'source/demos/stokes.py'
sphinx-apidoc -f -T -o source/ ../firedrake ../firedrake/cython/.so
FIREDRAKE_BUILDING_DOCS=1 sphinx-build -b html -W -d build/doctrees source build/html
Running Sphinx v8.2.3
/home/tcalder/venv-firedrake/firedrake/docs/source/conf.py:318: SyntaxWarning: invalid escape sequence '\D'
''',
/home/tcalder/venv-firedrake/firedrake/docs/source/conf.py:318: SyntaxWarning: invalid escape sequence '\p'
''',
/home/tcalder/venv-firedrake/firedrake/docs/source/conf.py:318: SyntaxWarning: invalid escape sequence '\p'
''',
/home/tcalder/venv-firedrake/firedrake/docs/source/conf.py:318: SyntaxWarning: invalid escape sequence '\h'
''',
/home/tcalder/venv-firedrake/firedrake/docs/source/conf.py:318: SyntaxWarning: invalid escape sequence '\p'
''',
loading translations [en]... done

Extension error!

Versions

• Platform: linux; (Linux-5.15.167.4-microsoft-standard-WSL2-x86_64-with-glibc2.39)
• Python version: 3.12.3 (CPython)
• Sphinx version: 8.2.3
• Docutils version: 0.21.2
• Jinja2 version: 3.1.6
• Pygments version: 2.19.1

Last Messages

None.

Loaded Extensions

None.

Traceback

  File "/home/tcalder/venv-firedrake/lib/python3.12/site-packages/sphinx/registry.py", line 544, in load_extension
    raise ExtensionError(
sphinx.errors.ExtensionError: Could not import extension sphinxcontrib.inkscapeconverter (exception: No module named 'sphinxcontrib.inkscapeconverter')

The full traceback has been saved in:
/tmp/sphinx-err-hhsu53bd.log

To report this error to the developers, please open an issue at https://github.com/sphinx-doc/sphinx/issues/. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
WARNING! There are options you set that were not used!
WARNING! could be spelling mistake, etc!
There are 3 unused database options. They are:
Option left: name:-b value: html source: command line
Option left: name:-d value: build/doctrees source: command line
Option left: name:-W (no value) source: command line
make: *** [Makefile:118: buildhtml] Error 2

Thank you for any assistance.

@JDBetteridge

[connorjward]

I think you don't have the right set of dependencies installed. The dependencies we need for the docs are listed here. You can either install them manually or run pip install -e '/path/to/firedrake[docs]'. In particular it looks like your version of Sphinx is too new (we observed 8.2.0 breaking stuff).

You may also need to apt install inkscape.

[tcalderon-space]

got it thank you! for the pip install -e would that need to occur with the virtual environment activated?