Skip to content

[WIP] Docs: improve parameter formatting using custom Sphinx domain#6639

Open
eebasso wants to merge 95 commits intoBLAST-WarpX:developmentfrom
eebasso:docs-flexvar-extension
Open

[WIP] Docs: improve parameter formatting using custom Sphinx domain#6639
eebasso wants to merge 95 commits intoBLAST-WarpX:developmentfrom
eebasso:docs-flexvar-extension

Conversation

@eebasso
Copy link
Copy Markdown
Contributor

@eebasso eebasso commented Mar 5, 2026

Add a custom Sphinx domain for documenting parameters. Supports names containing characters like <, >, /, commas, etc.

This PR is inspired by the AMReX documentation of runtime parameters, which uses the Sphinx Python domain directive py:data in RuntimeParameters.rst. However, this fails for invalid Python variable names such as <species_name>.xmin,ymin,zmin that commonly occur in the WarpX documentation.

This domain solves that problem and allows use of parameter names such as <species_name>.xmin,ymin,zmin that do not work with the standard Sphinx Python domain.

The options of the fv:var directive build on the standard proposed by #6576

This is how the Simulation Time section rendered:

Screenshot 2026-03-04 162421

@eebasso eebasso changed the title Docs: Sphinx extension for WarpX parameters Docs: new format for inputs Mar 10, 2026
@eebasso eebasso changed the title Docs: new format for inputs Docs: format parameters using custom Sphinx domain Mar 10, 2026
@eebasso eebasso changed the title Docs: format parameters using custom Sphinx domain Docs: improve parameter formatting using custom Sphinx domain Mar 10, 2026
@RemiLehe RemiLehe self-assigned this Mar 24, 2026
@RemiLehe RemiLehe requested a review from EZoni March 24, 2026 13:43
@eebasso eebasso changed the title Docs: improve parameter formatting using custom Sphinx domain [WIP] Docs: improve parameter formatting using custom Sphinx domain Mar 31, 2026
"kg": ["kilogram", "kilograms"],
"V": ["volt", "volts"],
"eV": ["electronvolt", "electronvolts", "electron volt", "electron volts"],
"T": ["Telsa", "Telsas"],
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"T": ["Telsa", "Telsas"],
"T": ["Tesla", "Teslas"],

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Btw, is this case sensitive? What happens if a user types "tesla"

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just want to comment that a "user" in this context would be a contributor, correct? I think it's fair to request that contributors follow contributing guidelines (which in this case could include "write units in formulas when adding an input parameter to the documentation").

This is what I was trying to communicate during the meeting, as an alternative solution to over-engineering guardrails against variations of inputs, typos, etc. - alternative that relies on contributors following contributing guidelines and reviewers enforcing them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component: documentation Docs, readme and manual

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants