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

Fix docs build warnings and generate API docs with autosummary extension #494

Merged
merged 10 commits into from
Oct 17, 2024
Merged

Fix docs build warnings and generate API docs with autosummary extension #494

merged 10 commits into from
Oct 17, 2024

Conversation

yousefmoazzam
Copy link
Collaborator

@yousefmoazzam yousefmoazzam commented Oct 17, 2024 •
edited
Loading

Fixes #468
Fixes #486
Fixes #487
Fixes #490
Doesn't solve #492, but instead finds a workaround via not using | in conjunction with certain types

Checklist

  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have made corresponding changes to the documentation

@yousefmoazzam
Move generic_array type alias to separate module
188637b
@yousefmoazzam
Use Union in generic_array type alias
79e4b77 
See #492 for more details
@yousefmoazzam
Mock imports in docs build with autodoc_mock_imports
52e2a7a 
See #490 for more details.

Maybe there's differences between `autodoc_mock_imports` and
`autosummary_mock_imports`, but for now, `autodoc_mock_imports` seems to
do what is needed, so will carry on using `autodoc_mock_imports` untill
there's a reason to distinguish between the two.
@yousefmoazzam
Add hdf5plugin to sphinx mock imports
07f4759
@yousefmoazzam
Remove unnecessary mocks in sphinx docs config
c43e136 
The modules removed are either no longer used in httomo, or are in the
docs environment now, so the mocking of them by sphinx can safely be
removed without any issues.
@yousefmoazzam
Use Union for a union type involving h5py
252bacb 
See #492 for more details
@yousefmoazzam
Add httomo_backends to sphinx mock list
090ac1d 
The YAML checker needs `httomo_backends` purely for getting a path to
the YAML templates at runtime (ie, for functionality), which isn't
needed for just building the docs.
@yousefmoazzam
Generate API docs with sphinx autosummary extension
1fe92a1
@yousefmoazzam
Add rst template for class API docs
5ade8db
@yousefmoazzam
Remove unnecessary sphinx-apidoc step in docs build CI
ab99a46
@yousefmoazzam
Copy link
Collaborator Author

All warning in the docs build locally are gone, but the CI has one warning:

/home/runner/work/httomo/httomo/docs/source/developers/api.rst:4: WARNING: autosummary: failed to import httomo.cli.
Possible hints:
* AttributeError: module 'httomo' has no attribute 'cli'
* ImportError: cannot import name '__version__' from 'httomo' (/home/runner/work/httomo/httomo/httomo/__init__.py)
* ImportError:

Since it appears in CI only and not locally, it may need a bit more time to debug, so I'll make an issue for it to tackle after this PR; it's small in comparison to the main aim of this PR which was to:

  • get rid of as many easily tackle-able warnings in the docs build as possible (ie, get all the low hanging fruit)
  • generate API docs and include them in the main index.rst

@yousefmoazzam yousefmoazzam merged commit 4b857b3 into main Oct 17, 2024
3 checks passed
@yousefmoazzam yousefmoazzam deleted the api-docs-via-autosummary branch October 17, 2024 11:46
This was referenced Oct 17, 2024
Open
Closed
Closed
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
1 participant
@yousefmoazzam