Persistent cache during deployment with sphinx-autoapi?

doraemon 0
Viewed 22

I have been stuck with a problem for several days without solutions. I am trying to deploy local docs generated with Sphinx to Gitlab pages.

Below is my .gitlab-ci.yml on the root directory of the repos, and I am using the latest Ubuntu image:

  stage: deploy
  script:
  - apt update
  - apt install -y python3-pip
  - rm -rf /var/lib/apt/lists/*
  - pip install -U sphinx
  - pip install sphinx-autobuild
  - pip install sphinx-autoapi
  - pip install furo
  - sphinx-build -b html -E -a ./docs/ public
  artifacts:
    paths:
    - public
  only:
  - master

I have used the tags -E and -a during sphinx-build to force rebuild of all HTML pages, but the updated changes from the docstrings are still not picked up by Sphinx.

I am using sphinx-autoapi, and I have tried to point the autoapi_dirs to the correct directory:

autoapi_dirs = ['../mypackage']
autoapi_type = "python"

autoapi_options = [
    "members",
    "special-members",
    "undoc-members",
    "show-inheritance",
    "show-module-summary",
    "imported-members"
]

For my local build, the documentation can be updated accordingly, but for the deployment on Gitlab pages, each deployed version still sticks to the old documentation. I am not sure what else I can do to resolve this problem? Did I miss anything during the deployment?

Thank you for any suggestions :)

docstring python-sphinx gitlab python
1 Answers

After close to one week of hunting the bugs, I have managed to resolve the above-mentioned problem:

Only the arguments and typehints part of the docs cannot be shown correctly even after pip install -e mypackage every time and making sure that the conf.py is pointing to the correct directory.

I found out later that this is caused by B902 error (Link: https://pypi.org/project/flake8-bugbear/). I have a mixture of different method types in my class, I have previously only used the self argument for methods that need to access the attributes of the class, and I didn't used self for other methods that do not need the class attributes.

Nevertheless, what is puzzling to me is that flake8 and and sphinx compilation don't actually flag these as errors. I also have no problems using these methods in scripts either. The only problem is that sphinx-autoapi cannot output the docs correctly for these class methods that don't have self as the first argument. And I only discovered these errors later when including additional plugin for flake8 that pick up these errors.

doraemon0
Related