astropy / astropy/astropy-integration-testing

Integration testing but for doc build

Open
#34 1 comment 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
4
Forks
6
PR merge metrics
No merged PRs in 30d

Description

Example situation: `astropy` merges a PR that does not break downstream CI but would break downstream doc build (e.g., type-hinting in function signature of an inherited class that is being rendered in downstream doc). Currently, downstream only build docs against stable astropy (e.g., ReadTheDocs PR build). Therefore, such breakage will not manifest until `astropy` actually does a release, which is undesirable.

Proposed solution: Have infrastructure to build downstream docs using dev version of astropy. Theoretically this can be accomplished by, say, running sphinx-build for downstream docs in tox and see if it builds, while turning all warnings into exceptions.

Pros:

* Catch `astropy` code change breaking downstream doc build before `astropy` is released.

Cons:

* More burden on `astropy` infrastructure maintainers who now have to monitor the logs and alert downstream maintainers to fix any breakage, which may or may not be caused by `astropy` changes.
* We also have to remember to sync our integration doc build settings to reflect changing downstream practices.

Out of scope:

* Downstream packages do not have docs.
* Downstream packages do not use Sphinx.
* Downstream packages that already have broken doc build or are ignoring doc build warnings.

Alternative: Downstream adds a CI job to build their own docs against dev version of astropy using their own infrastructure.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the proposed tox-based workflow and how downstream documentation is built with sphinx-build. Identify which downstream packages are in scope and how warnings should become exceptions. Done means a documented integration process can build those downstream docs against the development version of astropy and expose breakage before release.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
ci-cd, documentation, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.