C++ demos document generation #3052

ampdes · 2024-02-10T21:56:10Z

An illustration for one of the demos: biharmonic equation

jhale · 2024-02-11T11:05:48Z

I think we would like to keep the single source file per demo approach.

Jupytext, the tool we use to convert light formatted Python to myst flavoured markdown, also supports converting light formatted C++ to myst flavoured markdown, which can then be included in sphinx using thr myst-parser module.

jhale · 2024-02-11T11:13:35Z

Additionally, this will require converting the existing rst comments to myst flavoured markdown. There is an automated tool to do this.

https://docs.readthedocs.io/en/stable/guides/migrate-rest-myst.html

garth-wells · 2024-02-12T10:31:15Z

Thanks for looking at this.

We aim with the doc system to be as 'standard' and simple as possible, especially at the lowest levels in the processing chain. We've seen (many times over now!) that we're not able to maintain bespoke doc processing.

Ideally on the C++ we can just run doxygen and not bring in CMake or any Python dependencies at this level, and keep all the Python-required handling in once place (python/doc).

jhale · 2024-02-12T11:05:44Z

@garth-wells I'm having a chat with @ampdes in Slack #development, I think we've found a good solution; for the demos we use light formatted C++ + myst-flavoured markdown + jupytext + sphinx/breathe, just like for the Python demos. It's been very robust so far in Python.

A link to the C++ demos will appear here:

https://docs.fenicsproject.org/dolfinx/v0.7.3/cpp/

Everything else stays the same, including the standard doxygen build for API documentation and the CI steps.

ampdes · 2024-02-13T00:41:57Z

This is not yet configured to run in github workflows.
The cmake still exists, since it was easier to build it using cmake.

jorgensd · 2024-02-13T07:17:49Z

cpp/demo/hyperelasticity/main.cpp

+//     display_name: C++17
+//     language: C++17


Can we do C++20 here? That is the minimal required standard we have for the actual code.

Specifying kernel_spec is not necessary. This is only needed when this file is opened in a notebook environment, then kernel_spec will be used for a kernel with interactive compiler.
I was trying xeus-cling locally (and not in dolfinx docker containers) and this jupytext metadata is a remant from that explore.

One could have just got hold of main.cpp file and run

~/.local/bin/jupytext --set-formats cpp,md main.cpp

to bind .cpp with a .md file, which results in

--- jupyter: jupytext: cell_metadata_filter: -all formats: cpp,md main_language: c++ text_representation: extension: .md format_name: markdown format_version: '1.3' jupytext_version: 1.16.1 ---

in .md file and

// --- // jupyter: // jupytext: // cell_metadata_filter: -all // formats: cpp:light,md // text_representation: // extension: .cpp // format_name: light // format_version: '1.5' // jupytext_version: 1.16.1 // ---

.cpp file.

https://jupytext.readthedocs.io/en/latest/advanced-options.html

I will simply remove all kernel_spec.

Actually only

~/.local/bin/jupytext --set-formats cpp main.cpp

is needed for each main.cpp file to populate with jupytext header, which will then be used later to convert to .md

I missed this discussion; does xeus-cling work?

I was presuming that this jupytext header is needed for reading and then converting to .md files.
It turns out that all these specifications are only for connecting .md or .cpp files to notebook files.

All these are deleted.

I didn't yet try xeus-cling with dolfinx.

Interesting, so perhaps we can also reduce or remove them in the .py files.

* Rename README to README.md in demo * Fix typos in doc of custom_kernel * Add basic documentation for hyperelasticity

* create a CMakeLists for documentation * supply INPUT and OUTPUT DIRS in Doxygen from Cmake * add FindSphinx * restructure source/index.rst to include demo.rst * api.rst was previously index.rst

* include flags for code blocks in demo cpp file(s) * create demo explanation as rst in /doc dir * refer code snippets in demo rst file

* add jupyter_process for cpp demo * convert biharmonic demo doc to myst * index demo.rst * copy python conf.py to cpp docs

* Add problematic files back

* C++ demos are organized in directory

* add jupytext specifications * update jupytext_process to include all demos

* delete CMakeLists.txt * revert Doxyfile * revert conf.py

jhale · 2024-02-14T16:46:07Z

cpp/doc/source/jupytext_process.py

+            with open(myst_file, "w") as fw:
+                fw.write(cpp_myst_text)
+
+            # There is a posibility to use jupyter-notebooks with C++/C kernels


I feel C++ and Notebooks is a bit of an edge use case.

However, free to export them, but don't link to them at this stage; someone could take a look and see if https://github.com/jupyter-xeus/xeus-cling works with the conda FEniCS packages.

jhale

Still a few more things to do; looking very good.

jhale · 2024-02-14T16:50:41Z

cpp/demo/biharmonic/main.cpp

-// .. math::
-//    u            &= 0 \quad {\rm on} \ \partial\Omega \\
-//    \nabla^{2} u &= 0 \quad {\rm on} \ \partial\Omega
+// $$


Would be better to use the amsmath environments rather than $$

https://myst-parser.readthedocs.io/en/v0.14.0/using/syntax-optional.html#syntax-amsmath

One could use both $$ and amsmath simultaneously.

jhale · 2024-02-14T16:51:10Z

cpp/doc/Doxyfile

-                         ../dolfinx/common/loguru.cpp
+                         ../dolfinx/common/loguru.cpp \
+                        # TODO: resolve Doxygen parsing in:
+                        #  ../dolfinx/fem/interpolate.h \


Please discuss in Slack if struggling.

jhale · 2024-02-14T16:52:14Z

cpp/demo/biharmonic/main.cpp

+// ---
+// jupyter:
+//   jupytext:
+//     cell_metadata_filter: -all


What does this do?

It turns out it isnt needed unless for connecting the scripts to notebooks.

* Switch WARN_AS_ERROR to ON in Doxyfile * conf.py cleanup

jhale · 2024-02-20T15:26:09Z

This looks close to being ready to merge?

jhale · 2024-02-22T15:44:43Z

I'm going to merge this, cleanup and tweaking can be done later.

garth-wells · 2024-02-25T10:36:56Z

@ampdes very nice job.

ampdes mentioned this pull request Feb 10, 2024

Generate documentation for C++ demos #3012

Closed

jorgensd reviewed Feb 13, 2024

View reviewed changes

mscroggs linked an issue Feb 13, 2024 that may be closed by this pull request

Generate documentation for C++ demos #3012

Closed

ampdes marked this pull request as ready for review February 13, 2024 23:07

ampdes added 9 commits February 14, 2024 00:07

Fix typo and add doc for demo (FEniCS#3012)

fab01b5

* Rename README to README.md in demo * Fix typos in doc of custom_kernel * Add basic documentation for hyperelasticity

Build documentation (FEniCS#3012)

bb1c237

* create a CMakeLists for documentation * supply INPUT and OUTPUT DIRS in Doxygen from Cmake * add FindSphinx * restructure source/index.rst to include demo.rst * api.rst was previously index.rst

Add rst files for demo (FEniCS#3012)

87931a4

* include flags for code blocks in demo cpp file(s) * create demo explanation as rst in /doc dir * refer code snippets in demo rst file

Setup jupyter_process and biharmonic demo

a741219

* add jupyter_process for cpp demo * convert biharmonic demo doc to myst * index demo.rst * copy python conf.py to cpp docs

Switch off Doxygen warn as error

8b4f517

* Add problematic files back

Copy demo into docs subdirs

9c3b79f

* C++ demos are organized in directory

Add all demos

31b66b3

* add jupytext specifications * update jupytext_process to include all demos

Clean jupytext header, clean jupytext_process

829b59d

Switch back to ccpp.yml execution

fee2eb3

* delete CMakeLists.txt * revert Doxyfile * revert conf.py

ampdes force-pushed the build-doc-pipeline branch from bc46e5a to fee2eb3 Compare February 13, 2024 23:07

Remove extra file

74150ab

jhale reviewed Feb 14, 2024

View reviewed changes

jhale and others added 6 commits February 14, 2024 17:55

Merge branch 'main' into build-doc-pipeline

8c068f5

Cleaning up

20b44db

Pure conversion and some clean up

0aa4152

Merge branch 'main' into build-doc-pipeline

bf2ec75

Ruff format jupytext_process.py

2052d9f

Clean up

0c61ebe

* Switch WARN_AS_ERROR to ON in Doxyfile * conf.py cleanup

ampdes force-pushed the build-doc-pipeline branch from a55eb23 to 0c61ebe Compare February 20, 2024 12:06

Merge branch 'main' into build-doc-pipeline

f9dc3c8

ampdes and others added 2 commits February 20, 2024 16:51

Ruff format conf.py

f389a8b

Merge branch 'main' into build-doc-pipeline

1e98408

garth-wells added the documentation Documentation improvements or fixes label Feb 21, 2024

jhale added this pull request to the merge queue Feb 22, 2024

Merged via the queue into FEniCS:main with commit 476c61c Feb 22, 2024
12 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

C++ demos document generation #3052

C++ demos document generation #3052

ampdes commented Feb 10, 2024

jhale commented Feb 11, 2024 •

edited

jhale commented Feb 11, 2024

garth-wells commented Feb 12, 2024

jhale commented Feb 12, 2024 •

edited

ampdes commented Feb 13, 2024

jorgensd Feb 13, 2024

ampdes Feb 13, 2024 •

edited

ampdes Feb 13, 2024

jhale Feb 14, 2024

ampdes Feb 14, 2024

jhale Feb 21, 2024

jhale Feb 14, 2024

jhale left a comment

jhale Feb 14, 2024

ampdes Feb 14, 2024

jhale Feb 14, 2024

jhale Feb 14, 2024

ampdes Feb 14, 2024

jhale commented Feb 20, 2024

jhale commented Feb 22, 2024

garth-wells commented Feb 25, 2024

C++ demos document generation #3052

C++ demos document generation #3052

Conversation

ampdes commented Feb 10, 2024

jhale commented Feb 11, 2024 • edited

jhale commented Feb 11, 2024

garth-wells commented Feb 12, 2024

jhale commented Feb 12, 2024 • edited

ampdes commented Feb 13, 2024

Choose a reason for hiding this comment

ampdes Feb 13, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jhale left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jhale commented Feb 20, 2024

jhale commented Feb 22, 2024

garth-wells commented Feb 25, 2024

jhale commented Feb 11, 2024 •

edited

jhale commented Feb 12, 2024 •

edited

ampdes Feb 13, 2024 •

edited