Enable Python docs on readthedocs #246
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
We require newer version of swig that is only present in ubuntu-22 (it should become the default soon anyway) because of -doxygen flag which is needed to generate python docs. This also changes the way in which python is configured. The current approach is deprecated: https://docs.readthedocs.io/en/latest/config-file/v2.html#python-version
We need to generate the bindings files so that they can be used to generate python docs. Readthedocs doesn't have to do a full build in order to generate documentation so it doesn't use the cmake specified workflow. It has a custom workflow that needs to run swig manually. The approach here tries to use all interface files except `shared.i`, this may break in the future if there is for example another shared file. The actual list is hardcoded in cmake: https://github.com/rpm-software-management/dnf5/blob/main/bindings/CMakeLists.txt#L51-L56
Autoapi uses a custom parser to read in the doc strings and doesn't need to include the python modules. This allows to generate the docs even without full build of the library, we just need to run swig but there is no need to compile the library with the swig layer to create working Python module. This is only used in readthedocs because sphinx-autoapi is currenly not packaged in fedora. However since in fedora we do regular full builds it is not a problem and Autodoc can be used normally.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Follow up for: #163
Currently Python docs on readthedocs are empty: https://dnf5.readthedocs.io/en/latest/api/python/libdnf5_base_base.html
This is because readthedocs doesn't use
cmakeworkflow to create the documentation (since it doesn't need to build the library to generate the docs). This PR adds readthedocs workflow to generate it using Sphinx AutoAPI that parses documented swig code itself, it doesn't need (to include) working Python module.This is only used in readthedocs because sphinx-autoapi is currenly not packaged in fedora. However since in fedora we do regular full builds it is not a problem and Autodoc can be used normally.
For: #213