Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sphinx Documentation w. Python V3.12 #281

Closed
hefl99 opened this issue Apr 17, 2024 · 3 comments
Closed

Sphinx Documentation w. Python V3.12 #281

hefl99 opened this issue Apr 17, 2024 · 3 comments

Comments

@hefl99
Copy link
Contributor

hefl99 commented Apr 17, 2024

Itom Documentation does not build with latest Python V3.12 due to package conflict w. breathe v4.35.0.
This installs also sphinx v.7.3.5, but leads to interface conflict since ASTParameterQualifiers seems to be discontinued.
Fixed it temporarily by downgrading sphinx to v5.3.0 and numpydoc to v1.6.0.

This is a mayor issue for future ITOM_Release, but it seems to be noticed by the breathe develoers.

A ticket has been raised recently.
breathe-doc/breathe#981

Action:
Change File "build_documentation.rst" to include latets workaround

@photoniker
Copy link
Contributor

My latest docu build was successful with Sphinx 7.2. 7.3 is quite new... Did you try some other Sphinx Major Version 7?

@photoniker
Copy link
Contributor

This issue was fix by Sphinx in version 7.3.6 Changelog.

I build the docu successfully
image

@hefl99 Please try the version 7.3.6 and close this issue, if the build was successfull.

@hefl99 hefl99 closed this as completed Apr 18, 2024
@hefl99
Copy link
Contributor Author

hefl99 commented Apr 18, 2024

That escalated quickly,

issue filed and closed at breathe within 24hrs. ^^
Sphinx has fixed the bug an backloged their releases up to version: v.7.3.0

In our documentation, I found a small error. "requirementsDocuBuild.txt" was named incorrectly.
Fixed it in corresponding branch an put up a pull-request.

Implemneted yesterday a workaround. I'll publish this code here, just in case

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

In the |itom| sources folder **itom/docs/userDoc**, you can find a
**requirementsDocuBuild.txt** file containing all further necessary python packages
and Sphinx extensions. Install them by using **pip**:

.. code-block: bat

    python.exe -m pip install -r requirementsDocuBuild.txt

Or Install it manually:

* `matplotlib <https://pypi.org/project/matplotlib/>`_
* `numpy <https://pypi.org/project/numpy/>`_
* `openpyxl <https://pypi.org/project/openpyxl/>`_
* `pandas <https://pypi.org/project/pandas/>`_
* `plotly <https://pypi.org/project/plotly/>`_
* `tables <https://pypi.org/project/tables/>`_
* `scikit learn <https://pypi.org/project/scikit-learn/>`_
* `scipy <https://pypi.org/project/scipy/>`_
* `seaborn <https://pypi.org/project/seaborn/>`_

Regarding Python3.12:

Running pip install breathe automatically installs sphinx v7.3.5.
However sphinx v5.3.0 is needed to allow compatibility with breathe.
Issue is reported: https://github.com/itom-project/itom/issues/281. 
Therefore run the following commands in the exact order:

* pip install sphinx==5.3.0
* pip install numpydoc==1.6.0
* pip install breathe==4.35.0
* pip install sphinxcontrib-moderncmakedomain

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

hefl99 added a commit that referenced this issue Apr 18, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants