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.

Sign up for GitHub

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

Jump to bottom

Enable Python docs on readthedocs #246

Merged
merged 4 commits into from
Feb 6, 2023
Merged

Enable Python docs on readthedocs #246

merged 4 commits into from
Feb 6, 2023

Commits on Feb 1, 2023

  1. There is no need to copy vector of IDs it is not changed

    @kontura
    kontura committed Feb 1, 2023
    Configuration menu
    Copy the full SHA
    bb419a3 View commit details
    Browse the repository at this point in the history

  2. Update readthedocs config file 

    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
    @kontura
    kontura committed Feb 1, 2023
    Configuration menu
    Copy the full SHA
    37859cd View commit details
    Browse the repository at this point in the history

  3. Run swig manually in the readthedocs workflow 

    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
    @kontura
    kontura committed Feb 1, 2023
    Configuration menu
    Copy the full SHA
    4814787 View commit details
    Browse the repository at this point in the history

  4. Use Autoapi instead of Autodoc to generate Python docs in readthedocs 

    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.
    @kontura
    kontura committed Feb 1, 2023
    Configuration menu
    Copy the full SHA
    f2158e7 View commit details
    Browse the repository at this point in the history