Skip to content

Replace :: with codeblocks in demos - #5414

Open
nwng04 wants to merge 16 commits into
mainfrom
nwng04/replace-demo-codeblocks
Open

Replace :: with codeblocks in demos#5414
nwng04 wants to merge 16 commits into
mainfrom
nwng04/replace-demo-codeblocks

Conversation

@nwng04

@nwng04 nwng04 commented Sep 1, 2026

Copy link
Copy Markdown

Description

Currently codeblocks are defined in Firedrake demos using ::.
This change replaces all uses of :: with .. codeblock:: python. This provides more control over code formatting.

@nwng04 nwng04 changed the title Replace :: with codeblocks Replace :: with codeblocks in demos Sep 1, 2026
connorjward
connorjward requested changes Sep 1, 2026
View reviewed changes

@connorjward connorjward left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Seems basically fine and is probably a nice improvement.

Comment thread demos/benney_luke/benney_luke.py.rst Outdated
Comment thread demos/vlasov_poisson_1d/vp1d.py.rst Outdated
@nwng04
nwng04 force-pushed the nwng04/replace-demo-codeblocks branch from 4d27d24 to 06436b3 Compare September 3, 2026 08:42
@nwng04
nwng04 requested a review from leo-collins September 3, 2026 09:30
@nwng04
nwng04 marked this pull request as ready for review September 3, 2026 09:30
leo-collins
leo-collins requested changes Sep 3, 2026
View reviewed changes

@leo-collins leo-collins left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

There is a pylit command in docs/Makefile that needs updating.

Also test_demos_run.py needs updating. Currently all these tests are passing trivially because the files contain no actual python code.

Comment thread docs/source/extruded-meshes.rst
leo-collins
leo-collins reviewed Sep 3, 2026
View reviewed changes
Comment thread docs/source/checkpointing.rst
Comment on lines -81 to 89
::
.. code-block:: python

HDF5 "example.h5" {
FILE_CONTENTS {
group /
group /topologies
group /topologies/firedrake_mixed_meshes
group /topologies/firedrake_mixed_meshes/meshA
group /topologies/firedrake_mixed_meshes/meshA/firedrake_mixed_function_spaces

@leo-collins leo-collins Sep 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This is not python code

leo-collins
leo-collins reviewed Sep 3, 2026
View reviewed changes
Comment thread docs/source/zenodo.rst
Comment on lines -43 to 45
on Zenodo). For example::
on Zenodo). For example:

.. code-block::

firedrake-zenodo -t "My paper title"

@leo-collins leo-collins Sep 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Not python

@nwng04

nwng04 commented Sep 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Previously, .. code-block:: python was used to present code in the demo that was not intended to be compiled with pylit. I have replaced them with .. code-block:: text. Also, all shell/bash code blocks are replaced with .. code-block:: console for consistency.

Also, found some demos that used # to provide indentation in code blocks. These symbols used for indentation were visible in demos [e.g. in the while loop of https://www.firedrakeproject.org/demos/camassaholm.py.html]. I replaced these with :dedent:.

@connorjward

connorjward commented Sep 7, 2026

Copy link
Copy Markdown
Contributor

@leo-collins hoping you can review this one

connorjward
connorjward requested changes Sep 8, 2026
View reviewed changes

@connorjward connorjward left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Made it about 80% through. Will review the rest shortly. This is great, thankless work - thank you!

Comment thread demos/adaptive_multigrid/adaptive_multigrid.py.rst
To mark cells by some other criterion, refine the finest mesh yourself and add the result, which is all that :meth:`~.HierarchyBase.adapt` does once it has marked:

.. code-block:: python
.. code-block:: none

@connorjward connorjward Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
.. code-block:: none
.. code-block:: python

Comment thread CITATION.rst
If you publish results using Firedrake, we would be grateful if you would cite the Firedrake user manual::
If you publish results using Firedrake, we would be grateful if you would cite the Firedrake user manual:

.. code-block:: python

@connorjward connorjward Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
.. code-block:: python
.. code-block:: text

Comment thread demos/extruded_shallow_water/extruded_shallow_water.py.rst
\int_{\Omega} w \cdot u_h \, dx = \int_{\Omega} w \cdot u_0 \, dx + \frac{\Delta t}{2} \int_{\Omega} (\nabla \cdot w) p_0 \, dx \quad \forall w \in W

.. code-block:: python
.. code-block:: none

@connorjward connorjward Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
.. code-block:: none
.. code-block:: python

Comment thread demos/extruded_shallow_water/extruded_shallow_water.py.rst
\int_{\Omega} w \cdot u_1 \, dx = \int_{\Omega} w \cdot u_h \, dx + \frac{\Delta t}{2} \int_{\Omega} (\nabla \cdot w) p_1 \, dx \quad \forall w \in W

.. code-block:: python
.. code-block:: none

@connorjward connorjward Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
.. code-block:: none
.. code-block:: python

Comment thread demos/extruded_shallow_water/extruded_shallow_water.py.rst
\int_{\Omega} \phi \, p_1 \, dx = \int_{\Omega} \phi \, p_0 \, dx - \Delta t \int_{\Omega} \phi (\nabla \cdot u_h) \, dx \quad \forall \phi \in X

.. code-block:: python
.. code-block:: none

@connorjward connorjward Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
.. code-block:: none
.. code-block:: python

Comment thread demos/extruded_shallow_water/extruded_shallow_water.py.rst
We also print the current simulation time at each step for tracking progress.

.. code-block:: python
.. code-block:: none

@connorjward connorjward Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
.. code-block:: none
.. code-block:: python

Comment thread docs/source/extruded-meshes.rst
which results in the following mesh topology.::
which results in the following mesh topology.

.. code-block:: python

@connorjward connorjward Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
.. code-block:: python
.. code-block:: text

Comment thread docs/source/extruded-meshes.rst
which results in the following mesh topology.::
which results in the following mesh topology.

.. code-block:: python

@connorjward connorjward Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
.. code-block:: python
.. code-block:: text

connorjward
connorjward requested changes Sep 8, 2026
View reviewed changes

@connorjward connorjward left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

All done now. Once these fixes are in I think we're good to merge.

This PR is going into main not release, but a release is just around the corner so I'm not concerned.

Comment thread docs/source/citing.rst
<https://doi.org/10.25561/104839>`_::
<https://doi.org/10.25561/104839>`_:

.. code-block:: python

@connorjward connorjward Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Suggested change
.. code-block:: python
.. code-block:: text

leo-collins
leo-collins reviewed Sep 8, 2026
View reviewed changes
Comment thread docs/source/preconditioning.rst
Comment on lines 75 to 87
decomposition that supports the patches. This is set via the
`distribution_parameters` kwarg of the :func:`.Mesh` constructor. For
instance, vertex-star patches require ::
instance, vertex-star patches require:

.. code-block:: python

distribution_parameters["overlap_type"] = (DistributedMeshOverlapType.VERTEX, 1)

while Vanka patches require ::
while Vanka patches require:

.. code-block:: python

distribution_parameters["overlap_type"] = (DistributedMeshOverlapType.VERTEX, 2)

@leo-collins leo-collins Sep 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

These code blocks need to be indented into the .. note:: block

leo-collins
leo-collins requested changes Sep 8, 2026
View reviewed changes

@leo-collins leo-collins left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This seems pretty much fine now

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

Reviewers

@connorjward connorjward connorjward requested changes
@leo-collins leo-collins leo-collins requested changes

Requested changes must be addressed to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@nwng04 @connorjward @leo-collins