[go: up one dir, main page]

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.

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

Merged
merged 29 commits into from
Sep 25, 2024
Merged

Documentation API description #1141

merged 29 commits into from
Sep 25, 2024

Conversation

lee1043
Copy link
Contributor
@lee1043 lee1043 commented Sep 25, 2024

Auto-generation of API description from docstrings in the code -- thanks to the instruction from @tomvothecoder

@lee1043 lee1043 self-assigned this Sep 25, 2024
@lee1043 lee1043 marked this pull request as ready for review September 25, 2024 06:12
@lee1043
Copy link
Contributor Author
lee1043 commented Sep 25, 2024

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 .github/workflow directory, while xCDAT does not. Should I remove documentation.yaml file?

$ make html
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.

@@ -1,5 +1,5 @@
name: Docs
on: [push, pull_request, workflow_dispatch]
on: [pull_request, workflow_dispatch]
Copy link
Collaborator

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:

  1. The current documentation.yaml will rebuild the documentation every time, which overwrites the latest stable version -- set this job to only run when push is initiated (example in e3sm_diags)
  2. 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:

  1. You can combine documentation.yaml into build_workflow.yaml by creating a separate publish-docs job that only runs with push (example in e3sm_diags)

@lee1043
Copy link
Contributor Author
lee1043 commented Sep 25, 2024

My local html build started to show auto-generated pages! Many thanks to @tomvothecoder!

Screenshot 2024-09-25 at 11 43 53 AM

@lee1043
Copy link
Contributor Author
lee1043 commented Sep 25, 2024

@tomvothecoder thanks for your review and suggestions!

@lee1043 lee1043 merged commit e72674e into main Sep 25, 2024
4 checks passed
@lee1043 lee1043 deleted the lee1043-patch-1 branch September 25, 2024 19:58
@lee1043 lee1043 added the doc label Sep 25, 2024
@tomvothecoder
Copy link
Collaborator

Glad to see you got the docs to work!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants