-
Notifications
You must be signed in to change notification settings - Fork 39
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
Documentation API description #1141
Conversation
Update and rename utils.rst to api.rst
Github action CI build test is passed, but my local html build shows an error and html for API reference is not properly generated. I am not really understanding why it try to import actual functions. @tomvothecoder do you have any advice for me? I noticed that PMP has documentations.yml file in
Running Sphinx v6.2.1
loading pickled environment... done
[autosummary] generating autosummary for: api.rst, contributing.rst, index.rst, install.rst, metrics.rst, metrics_enso.rst, metrics_ext.rst, metrics_mean-clim.rst, metrics_mjo.rst, metrics_monsoon.rst, ..., metrics_sea_ice.rst, metrics_subdaily-precipitation.rst, overview.rst, pmp-using-cdp-guide.rst, pmpparser.rst, resources.rst, resources_legacy.rst, start.rst, supporting-data.rst, team.rst
WARNING: [autosummary] failed to import apply_landmask.
Possible hints:
* ValueError: not enough values to unpack (expected 2, got 1)
* KeyError: 'apply_landmask'
* ModuleNotFoundError: No module named 'apply_landmask'
WARNING: [autosummary] failed to import apply_oceanmask.
Possible hints:
* ValueError: not enough values to unpack (expected 2, got 1)
* KeyError: 'apply_oceanmask'
* ModuleNotFoundError: No module named 'apply_oceanmask'
WARNING: [autosummary] failed to import check_daily_time_axis.
Possible hints:
* KeyError: 'check_daily_time_axis'
* ValueError: not enough values to unpack (expected 2, got 1)
* ModuleNotFoundError: No module named 'check_daily_time_axis'
WARNING: [autosummary] failed to import check_monthly_time_axis.
Possible hints:
* ModuleNotFoundError: No module named 'check_monthly_time_axis'
* KeyError: 'check_monthly_time_axis'
* ValueError: not enough values to unpack (expected 2, got 1)
WARNING: [autosummary] failed to import create_land_sea_mask.
Possible hints:
* ModuleNotFoundError: No module named 'create_land_sea_mask'
* KeyError: 'create_land_sea_mask'
* ValueError: not enough values to unpack (expected 2, got 1)
WARNING: [autosummary] failed to import regrid.
Possible hints:
* KeyError: 'regrid'
* ModuleNotFoundError: No module named 'regrid'
* ValueError: not enough values to unpack (expected 2, got 1)
The default value for `navigation_with_keys` will change to `False` in the next release. If you wish to preserve the old behavior for your site, set `navigation_with_keys=True` in the `html_theme_options` dict in your `conf.py` file. Be aware that `navigation_with_keys = True` has negative accessibility implications: https://github.com/pydata/pydata-sphinx-theme/issues/1492
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
reading sources...
looking for now-outdated files... none found
no targets are out of date.
build succeeded, 6 warnings.
The HTML pages are in _build/html. |
.github/workflows/documentation.yaml
Outdated
@@ -1,5 +1,5 @@ | |||
name: Docs | |||
on: [push, pull_request, workflow_dispatch] | |||
on: [pull_request, workflow_dispatch] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Actually, you will need the push
still because push
is considered merging a pull request to main
via a commit.
A few issues I found:
- The current
documentation.yaml
will rebuild the documentation every time, which overwrites the latest stable version -- set this job to only run whenpush
is initiated (example in e3sm_diags) - There is no versioning of documentation by branch and package version -- consider Read The Docs for this. e3sm_diags uses
sphinx-multiversion
which involves a complex setup process
Other suggestions:
- You can combine
documentation.yaml
intobuild_workflow.yaml
by creating a separatepublish-docs
job that only runs withpush
(example in e3sm_diags)
My local html build started to show auto-generated pages! Many thanks to @tomvothecoder! |
@tomvothecoder thanks for your review and suggestions! |
Glad to see you got the docs to work! |
Auto-generation of API description from docstrings in the code -- thanks to the instruction from @tomvothecoder