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.
Example situation:
astropymerges 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 untilastropyactually 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:
astropycode change breaking downstream doc build beforeastropyis released.Cons:
astropyinfrastructure maintainers who now have to monitor the logs and alert downstream maintainers to fix any breakage, which may or may not be caused byastropychanges.Out of scope:
Alternative: Downstream adds a CI job to build their own docs against dev version of astropy using their own infrastructure.