Skip to content

ci: Add build docs step to PR workflows (and fix currently broken autodoc generation)#268

Merged
romanc merged 3 commits into
NOAA-GFDL:developfrom
romanc:romanc/docs-update
Oct 17, 2025
Merged

ci: Add build docs step to PR workflows (and fix currently broken autodoc generation)#268
romanc merged 3 commits into
NOAA-GFDL:developfrom
romanc:romanc/docs-update

Conversation

@romanc
Copy link
Copy Markdown
Collaborator

@romanc romanc commented Oct 16, 2025

Description

PR #205 added basic support for auto-generated docs from docstrings. Docs aren't automatically generated and published yet. Recent changes such as removing global_config.py, splitting GridSizer and SubGridSizer, or adding State thus weren't captured in the docs. This PR suggest to improve the situation with two measures

  1. We build the docs as part of the CI tests that run on PRs. This will catch us if we remove things that are still referenced in the docs. The additional check isn't required to merge (we can change that).
  2. To improve the situation when we add new modules / features, I suggest to slightly change the pull request template to include a specific reminder.

There's a discussion to have when we should start automatically publishing docs, see #269. In my opinion, this discussion is tangential because even if we automatically publish docs, we'd like to know if a PR would break building the docs.

We should also have a separate discussion about the structure of docs. This could fit nicely in the context of the package restructuring discussion, see #243.

How has this been tested?

The new workflow properly failed before adding the fixes, see here.

Checklist

  • My code follows the style guidelines of this project
  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • Any dependent changes have been merged and published in downstream modules
    N/A
  • New check tests, if applicable, are included

@romanc romanc marked this pull request as ready for review October 16, 2025 13:27
@romanc romanc changed the title wip: Add build docs step to PR workflows ci: Add build docs step to PR workflows (and fix currently broken autodoc generation) Oct 16, 2025
@FlorianDeconinck FlorianDeconinck added the Scheduled for next Release To be merged before the next release label Oct 16, 2025
@romanc romanc added this pull request to the merge queue Oct 17, 2025
Merged via the queue into NOAA-GFDL:develop with commit df30bcc Oct 17, 2025
6 of 8 checks passed
@romanc romanc deleted the romanc/docs-update branch October 20, 2025 10:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Scheduled for next Release To be merged before the next release

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants