UAL-RE / redata-commons

Commons code used by ReDATA codebases
MIT License
1 stars 2 forks source link

Update README.md for Sphinx documentation #9

Closed astrochun closed 3 years ago

astrochun commented 3 years ago

With docs published on ReadTheDocs, here are a few necessary changes to minimize docs maintainence.

Notes

RTD Build status badges cannot be fully customized. This means that (1) the label will always be called docs, and that (2) the color will always reflect the build status (green, red, etc.). In fewer words: we cannot make the RTDs badge style match the other ReDATA badges.

For documentation see: https://docs.readthedocs.io/en/stable/badges.html#status-badges and https://raw.githubusercontent.com/readthedocs/readthedocs.org/master/docs/badges.rst

Implemented in: docs/09_README

damian-romero commented 3 years ago

An issue with RTD badges:

RTDs badges are not fully customizable (see description above). For this reason, I had to name the label of the GitHub Actions Sphinx build status as sphinx, instead of docs (which would conflict with the RTDs badge).

Notice that this introduces a discrepancy with ReQUIAM_csv, where the Sphinx build badge is labeled docs. We may want to update badges across all our repositories at some point.

astrochun commented 3 years ago

An issue with RTD badges:

RTDs badges are not fully customizable (see description above). For this reason, I had to name the label of the GitHub Actions Sphinx build status as sphinx, instead of docs (which would conflict with the RTDs badge).

Their badge is not, but there are ways with shields.io to customize it. I did it for another repo. Here's what I did:

[![Read the Docs](https://img.shields.io/readthedocs/metallicity-stack-commons?color=blue&label=RTDs)](https://readthedocs.org/projects/metallicity-stack-commons/builds/)

Notice that this introduces a discrepancy with ReQUIAM_csv, where the Sphinx build badge is labeled docs. We may want to update badges across all our repositories at some point.

I prefer to have both docs builds. One from our GItHub actions, labelled as docs and another labelled as RTDs. Note that docs is the jobs name in the workflow.