You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The SymPDE documentation is set up differently from the PSYDAC documentation:
All pages in doc/ are written in reStructuredText, and doc/conf.py does not load a Markdown parser. PSYDAC writes its prose pages in Markdown with myst_parser.
doc/conf.py does not load a docstring extension, so the numpydoc sections of the docstrings (Parameters, Returns, Examples, ...) are rendered as plain headings. PSYDAC renders them as formatted fields with numpydoc.
SymPDE uses the alabaster theme, PSYDAC uses pydata_sphinx_theme.
We would like the two projects to have documentation that looks and is maintained in the same way.
Suggested solution
Use the same Sphinx extensions and options as PSYDAC (docs/source/conf.py), where they apply to SymPDE:
myst_parser, with myst_heading_anchors = 3;
numpydoc, with numpydoc_show_class_members = False;
sphinx_math_dollar, for $...$ math in docstrings;
the pydata_sphinx_theme theme.
Add the corresponding packages to the docs dependencies in pyproject.toml.
Convert all prose pages to Markdown: quick.rst, advanced.rst, examples/index.rst, math/index.rst, math/feec.rst (and multipatch.rst, added by Update Multipatch API #188). Their Sphinx directives (literalinclude, math, bibliography, topic, note, the custom expression-tree, ...) become MyST fenced directives.
Keep index.rst and api.rst in reStructuredText, as PSYDAC does for its main page and API pages, and include README.md in index.rst as PSYDAC does.
Keep the Markdown pages directly in doc/, since doc/ is the Sphinx source directory (PSYDAC needs a copy step in its Makefile only because its pages are outside docs/source/).
Check that the documentation still builds with -W, and that the example scripts still run in the documentation workflow.
Activity