JSBSim Python API documentation unavailable!

[viren3999]

This link: https://jsbsim-team.github.io/jsbsim/python/index.html is supposedly for the JSBSim Python API documentation. However, it appears to be blank for all the classes.

Also, the doxy2pydocs.py python program fails at runtime. It is attempting to parse .XML; however, those names' files don't exist in the directory.

Kindly help.

[bcoconni]

Thanks for the report. I'll investigate.

Could you be more specific about doxy2pydocs.py failure ? What is the command that generates the failure ? What is the error message ? Is Doxygen installed on your platform ? Which version ?

[viren3999]

In reference to doxy2pydocs.py

I get the following error (shown in the image) when I attempt to run it.

• I am running the latest version of Ubuntu
• Yes, Doxygen is installed on my platform

[bcoconni]

Thanks for the feedback. Regarding the failure of doxy2pydocs.py this should now be fixed following the commit f120ea9 in the branch master.

I still need to investigate about the reason why the classes doc point to blank pages. I think this is due to the docs generation that is executed before the Python module is built (i.e. the steps Build Python docs and Build JSBSim below should swapped):

jsbsim/.github/workflows/cpp-python-build.yml

Lines 503 to 510 in f120ea9

	- name: Build Python docs
	working-directory: build
	run: |
	touch documentation/html/.nojekyll
	sphinx-build -b html documentation documentation/html/python
	- name: Build JSBSim
	working-directory: build
	run: make -j2

[bcoconni]

This link: https://jsbsim-team.github.io/jsbsim/python/index.html is supposedly for the JSBSim Python API documentation. However, it appears to be blank for all the classes.

This should now be fixed. Please check and let us know if you find some issues.

[viren3999]

This link: https://jsbsim-team.github.io/jsbsim/python/index.html is supposedly for the JSBSim Python API documentation. However, it appears to be blank for all the classes.

This should now be fixed. Please check and let us know if found some issues

Yes Sir. It works now. Thank you.

One small query, since the doxy2pydocs.py is also fixed, I just wanted to know where and in what format does it generate the documentation. Is it in HTML?

Pardon me for my ignorance, for I am new to these things.

[bcoconni]

One small query, since the doxy2pydocs.py is also fixed, I just wanted to know where and in what format does it generate the documentation. Is it in HTML?

The utility doxy2pydocs.py only populates the doc strings in jsbsim.pyx from the docs extracted by Doxygen.
The actual HTML Python documentation is generated by sphinx with the following command:

sphinx-build -b html documentation documentation/html/python

The command must be run from the build directory.

[viren3999]

On running this command: shell sphinx-build -b html documentation documentation/html/python

The documentation build completes but raises a warning, as follows:

WARNING: autodoc: failed to import class 'FGLinearization' from module 'jsbsim'; the following exception was raised: Traceback (most recent call last):

File "c:\users\viren\appdata\local\programs\python\python37\lib\site-packages\sphinx\util\inspect.py", line 401, in safe_getattr return getattr(obj, name, *defargs)

AttributeError: module 'jsbsim' has no attribute 'FGLinearization'

[bcoconni]

You most likely need to rebuild the docs since the commit f120ea9 that I mentioned above has not been taken into account. Just run:

> rm -f documentation
> cmake ..
> sphinx-build -b html documentation documentation/html/python

This should rebuild the docs first with Doxygen then with doxy2pydocs.py. You will still need to manually execute sphinx.

[viren3999]

Well, I deleted the documentation folder, and ran cmake .. followed by sphinx-build -b html documentation documentation/html/python

The warning persists.

Note: I am using the latest version of the repository from github.

[bcoconni]

I have no such warning message on my side. Could try to rebuild everything from scratch (i.e. either delete you build directory or create a new one) ?

[viren3999]

I have no such warning message on my side. Could try to rebuild everything from scratch (i.e. either delete you build directory or create a new one)?

Sir, I have done exactly what you instructed.

Well, the warning persists (on Ubuntu as well as Windows). However, I don't think it is affecting the generation of python documentation.

I have attached a complete snapshot of the same.

[seanmcleod]

Looks like you have a version of the JSBSim python module installed that Sphinx is picking up that is older than the commit that added the FGLinearization class.

Hence the reason @bcoconni suggested rebuilding the source code via cmake .. in order to rebuild the JSBSim python module.

But I'm wondering whether you've previously installed the JSBSim python module via pip install and sphinx is picking up this older version?

[viren3999]

Looks like you have a version of the JSBSim python module installed that Sphinx is picking up that is older than the commit that added the FGLinearization class.

Actually, I did have the jsbsim module installed, but it is the latest version==1.1.3

Hence the reason @bcoconni suggested rebuilding the source code via cmake .. in order to rebuild the JSBSim python module.

Taking @bcoconni and your suggestions, I have uninstalled the python jsbsim module and now the docs build successfully.

Thanks a lot for that!

I am running a x64 Windows machine. I have built the VS 2017 solution in Release - x64 mode.

Lastly, how should I install the python module? Is it fine to do so via pip?

[bcoconni]

Lastly, how should I install the python module? Is it fine to do so via pip?

It all depends on whether you want to use a stable version of JSBSim or not. The utility pip installs the last stable version (1.1.3 at the moment).

However if you want to use the bleeding edge features from JSBSim or plan to participate to the C++ development then you must build the Python module yourself and install it with pip:

> python python/setup.py bdist_wheel
> pip install jsbsim --no-index -f python/dist

In the eventuality where you want to use both then I suggest to use Python virtual environments which allow you to use Python in different environments (different versions of the Python interpreter or different set of packages installed). You can then create a virtual environment with JSBSim stable and another environment for JSBSim development (this is what I do so that I can test against both versions of JSBSim i.e. 1.1.3 and the master branch).

[seanmcleod]

but it is the latest version==1.1.3

So as @bcoconni mentioned this is the latest stable version, not the latest in terms of matching the head of the master branch in github.

[viren3999]

Thank you @bcoconni & @seanmcleod for all the support provided regarding the issue. Highly appreciated sir.

As a small follow up to the above comment, I tried the steps mentioned by @bcoconni for installing the Python JSBSim module with the latest features of JSBSim.

I am facing the following error, sir. If I am not wrong, is it due to no C++ compiler present in my system path? If so how to deal with it? While running Cmake, the script had identified a C++ compiler in my system.

[bcoconni]

@viren3999 if you don't mind, I suggest that we close this issue and open a new one regarding the last point you brought. I am suspecting you have caught an entirely different bug 😄

[viren3999]

@viren3999 if you don't mind, I suggest that we close this issue and open a new one regarding the last point you brought.

Agreed Sir.

I am suspecting you have caught an entirely different bug 😄

Well, I feel someone is on a streak 😜

Thank you!