JSBSim separate repository for Python API usage examples + documentation in Sphinx

[agodemar]

I've been experimenting lately with Sphinx and Jupyter notebooks.

We can think of creating a side project to JSBSim, named for instance: jsbsim-python-examples, or jsbsim-python-api-usage, or similar.
Something that lives outside the main JSBSim repo and we can experiment with. If the experiments evolve in a decent project, we can update the current JSBSim online reference manual.

One advantage of Sphinx is that we can setup the project and produce both a documentation website, and a nicely formatted PDF.

Ideas?

[seanmcleod70]

A couple of weeks ago I came across this repo - AE6310 is about the application of numerical optimization methods to the design of engineering systems. which uses Sphinx and Jupyter notebooks mainly in order to generate an online version of the course notes via Github Pages, see - https://smdogroup.github.io/ae6310/

However, as I posted here - smdogroup/ae6310#1 I wanted an offline PDF version to read on a Kindle Scribe, so I forked the repo and added some build instructions to make use of Sphinx's LaTeX support to generate a PDF version of the notes, you can see how the PDF turned out here - https://github.com/seanmcleod70/ae6310/actions/runs/23159626872/artifacts/5950417366

So my thinking when I pinged @agodemar was that if we used the Sphinx approach with Jupyter notebooks etc. for the JSBSim manual we could fairly easily generate both an online version of the JSBSim manual hosted via Github pages and also a PDF version.

[bcoconni]

Looks good to me even though documentation is not my strong suit 😄

Regarding the name of the project jsbsim-python-examples seems better to me as the focus will, I guess, be more on the examples than on the Python API ?

Also I think that giving the ability to open the Jupyter notebooks with Google Colab was a good move for the JSBSim main site as people can test JSBSim with just one click. So I guess the Jupyter notebooks in that new repo should be keep that feature ?

[agodemar]

@seanmcleod70 @bcoconni
This is a proof of concept: https://agodemar.github.io/jsbsim-python-api-usage that originates from my repo https://github.com/agodemar/jsbsim-python-api-usage.
I didn't type any actual code yet ;-)
I made it by directing the GitHub Copilot agents integrated within my web dashboard. As an academic, I have access to quite a few of them, including Claude Opus 4.6, GPT-5.3-Codex, and others.

I will continue to experiment with it, tweaking notebooks, adding more significant examples (taken from the main JSBSim repo).
I'll change the name to jsbsim-python-examples - although we can use this project also to document the Python API itself.
I'll make sure to include a button "Open in Colab" like we have in the other examples.

Suggestions, directions, PRs are welcome

[bcoconni]

I'll change the name to jsbsim-python-examples

That was just a suggestion. If you have already picked a name, keep it like this.

[agodemar]

After few hours in my Easter break, with the help of clever agents and human supervision, the Sphinx based doc page is in good shape and its source repository is now a good starting template to experiment.

Feel free to fork and submit PRs

[seanmcleod70]

Looks good.

Quick comment, as opposed to a full PR. In 01_jsbsim_hello_world.

# Suppress verbose JSBSim console output
jsbsim.FGJSBBase().debug_lvl = 0

fdm = jsbsim.FGFDMExec(None)   # None → use data bundled with the pip package
fdm.set_debug_level(0)

Pretty sure having both calls to set the debug level = 0 is redundant.

fdm.set_debug_level(0) from python calls into:

jsbsim/src/FGFDMExec.h

Line 510 in 6c0e656

void SetDebugLevel(int level) {debug_lvl = level;}

Only potential advantage of jsbsim.FGJSBBase().debug_lvl = 0 I guess could be to suppress debug output that may be output during the ctor of FGFDMExec?

[seanmcleod70]

One minor typo in the same notebook. cmd-norm isn't in radians.

print(f" Elevator trim : {fdm['fcs/pitch-trim-cmd-norm']:.4f} rad")