search

CDCgov / multisignal-epi-inference

Python package for statistical inference and forecast of epi models using multiple signals
https://cdcgov.github.io/multisignal-epi-inference/
10 stars 1 forks source link

Build sphinx using either Markdown or a hybrid with rst #231

Open gvegayon opened 3 days ago

gvegayon commented 3 days ago
  1. Do we want to keep using rst? I Sphinx supports markdown (see here also). Maybe, a hybrid between the two would be a solution?

If you feel strongly that this is the better way to go, please open an issue and describe the "hybrid" solution a bit more. If you are on the fence, I think we can just continue with the current workflow and keep focused on higher-priority tasks.

Originally posted by @damonbayer in https://github.com/CDCgov/multisignal-epi-inference/issues/224#issuecomment-2200413117

dylanhmorris commented 2 days ago

I semi-duplicated this in #235. Will close that one.

dylanhmorris commented 2 days ago

The parameters

We're set on having .qmd for literate programming for the moment, and unless/until there's closer Quarto integration for Sphinx, those docs will always need to be rendered to something (.md, .rst, etc) before being handed off to Sphinx.

My preference: use .md rather than .rst

I slightly favor .qmd -> .md and the rest of the docs written in regular .md, as that comes closest to a single unified coding style.

Status quo (.rst) would also be fine

I'm also happy to stick with the status quo .qmd -> .rst and everything else in .rst if others prefer that.

Question

@gvegayon: by "hybrid" did you mean a mix of (non-Quarto) .md and .rst? If so, what do you see as the potential benefits?

dylanhmorris commented 2 days ago

Tagging @CDCgov/multisignal-epi-inference-devs for visibility.

damonbayer commented 2 days ago

Agree with all of what @dylanhmorris said above.