This is based on work done by @ansMHanmer in a draft PR, #319.
Overall, the aim is to be able to run Sphinx Gallery documentation generation on GitHub. Up until now, we have had to run this locally and committed the generated output to the repo. This was because of the complications with running realistic System Coupling cases involving real participant products and needing to get it all working with containers if running on GitHub.
The main changes relative the to the draft are:
Merge the Sphinx Gallery generation into the main docs job - as it is just a part of the doc build and the examples doc that is generated forms part of the complete documentation.
Modify gallery scripts to launch Fluent using "vanilla" launch commands without any explicit mention of container-related arguments. The PYFLUENT_LAUNCH_CONTAINER is what allows this, and this can be set in the workflow YAML.
Similarly, instead of using the pymapdl.Mapdl() call that explicitly expects to connect to a running MAPDL instance, replace with pymapdl.launch_mapdl() and set PYMAPDL_START_INSTANCE=FALSE.
Completely remove the docs/source/examples directory. As noted above, the Sphinx Gallery output used to have to be committed to source control, and the Sphinx doc build would then integrate the output into the rest of the doc as if it were manually written "rst".
Add some handling in the conf.py Sphinx configuration file to do some cleanup between gallery example runs. It was found it was necessary to switch the SyC container "user" to "runner" so that was sufficient permission on left over files for them to be deleted. Launching and removing the MAPDL container at the start and end of the examples requiring it is also handled in the same part of the Sphinx configuration.
NB The oscillating_plate example has changed somewhat in this process and the documentation is incomplete. The focus in this PR is on getting the mechanisms working - the doc content will be (re-)added in a follow-up.
This is based on work done by @ansMHanmer in a draft PR, #319.
Overall, the aim is to be able to run Sphinx Gallery documentation generation on GitHub. Up until now, we have had to run this locally and committed the generated output to the repo. This was because of the complications with running realistic System Coupling cases involving real participant products and needing to get it all working with containers if running on GitHub.
The main changes relative the to the draft are:
docsjob - as it is just a part of the doc build and the examples doc that is generated forms part of the complete documentation.PYFLUENT_LAUNCH_CONTAINERis what allows this, and this can be set in the workflow YAML.pymapdl.Mapdl()call that explicitly expects to connect to a running MAPDL instance, replace withpymapdl.launch_mapdl()and setPYMAPDL_START_INSTANCE=FALSE.docs/source/examplesdirectory. As noted above, the Sphinx Gallery output used to have to be committed to source control, and the Sphinx doc build would then integrate the output into the rest of the doc as if it were manually written "rst".conf.pySphinx configuration file to do some cleanup between gallery example runs. It was found it was necessary to switch the SyC container "user" to "runner" so that was sufficient permission on left over files for them to be deleted. Launching and removing the MAPDL container at the start and end of the examples requiring it is also handled in the same part of the Sphinx configuration.NB The
oscillating_plateexample has changed somewhat in this process and the documentation is incomplete. The focus in this PR is on getting the mechanisms working - the doc content will be (re-)added in a follow-up.