Skip to content

Replace :: with codeblocks in demos - #5414

Merged
connorjward merged 21 commits into
mainfrom
nwng04/replace-demo-codeblocks
Sep 10, 2026
Merged

Replace :: with codeblocks in demos#5414
connorjward merged 21 commits into
mainfrom
nwng04/replace-demo-codeblocks

Conversation

@nwng04

@nwng04 nwng04 commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

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
leo-collins
leo-collins reviewed Sep 3, 2026
View reviewed changes
Comment thread docs/source/zenodo.rst
@nwng04

nwng04 commented Sep 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor 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 Outdated
Comment thread CITATION.rst Outdated
Comment thread demos/extruded_shallow_water/extruded_shallow_water.py.rst Outdated
Comment thread demos/extruded_shallow_water/extruded_shallow_water.py.rst Outdated
Comment thread demos/extruded_shallow_water/extruded_shallow_water.py.rst Outdated
Comment thread demos/extruded_shallow_water/extruded_shallow_water.py.rst Outdated
Comment thread docs/source/extruded-meshes.rst Outdated
Comment thread docs/source/extruded-meshes.rst Outdated
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 Outdated
leo-collins
leo-collins reviewed Sep 8, 2026
View reviewed changes
Comment thread docs/source/preconditioning.rst
leo-collins
leo-collins previously 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

connorjward
connorjward previously approved these changes Sep 10, 2026
View reviewed changes
@connorjward

connorjward commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

Lets fix main via #5443, then I will update and merge this branch. I want to make sure that the docs build correctly before merging.

@connorjward
Demo fixes
37fd885 
* Speed up the demos on CI
* Move some old ..python code blocks to ..text now that ..python has a
  special meaning.
@connorjward

connorjward commented Sep 10, 2026

Copy link
Copy Markdown
Contributor

Just pushed a couple of fixes where previous .. code-block:: python blocks were now getting inserted into the script. Also sped up the broken demos (if FIREDRAKE_CI=1) because they took ages to run.

@connorjward
connorjward enabled auto-merge (squash) September 10, 2026 16:45
@connorjward
connorjward merged commit 154225c into main Sep 10, 2026
6 of 7 checks passed
@connorjward
connorjward deleted the nwng04/replace-demo-codeblocks branch September 10, 2026 18:28
pbrubeck pushed a commit that referenced this pull request Sep 18, 2026
@nwng04 nwng04
@leo-collins @connorjward @pbrubeck
Replace :: with codeblocks in demos (#5414)
f68e3c9 
* Add punctuation before each codeblock

* Makefile changes

* Add : punctuation to the end of paragraphs

* Specify code-blocks as python3 and remove python specification for docs/source files

* Convert back from python3 to python

* Update makefiles and remove non-python code blocks

* Add python keyword to make files

* Change sample code in demo from python to none

* Swap code-blocks to parsed-literals

* Revert parsed-literal back to code-block: console

* Revert from parsed-literal::

* Update pylit command in demo/makefile

* Revert cores from 6 to 2

* Update installation page and replace bash code-blocks with shell code-blocks

* Replace shell with console, specify types for blank code-blocks

* Found `#` used for indenting conde-blocks. Replace these with :dedent:

* Apply batched suggestions from code review

Co-authored-by: Connor Ward <c.ward20@imperial.ac.uk>

* some fixes

* Demo fixes

* Speed up the demos on CI
* Move some old ..python code blocks to ..text now that ..python has a
  special meaning.

---------

Co-authored-by: nwng04 <nwng04@gmail.com>
Co-authored-by: Leo Collins <leocollins511@gmail.com>
Co-authored-by: Connor Ward <c.ward20@imperial.ac.uk>
Co-authored-by: Leo Collins <collins.leo@proton.me>
pbrubeck added a commit that referenced this pull request Oct 2, 2026
@pbrubeck @claude
Goal-oriented demos: use code-blocks and get_marking_callback
22d2a96 
Since #5414 the demo tests extract only ``.. code-block:: python``
blocks, so these demos ran no code. The goal functional and the error
estimate now come from the callback that get_marking_callback returns.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@connorjward connorjward connorjward approved these changes
@leo-collins leo-collins leo-collins left review comments

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