Major overhaul of documentation#347
Conversation
teutoburg
changed the title
Replace nbsphinx + default theme with myst-nb + sphinx-book-theme, following the scopesim-targets canonical A* Vienna docs template. Add sphinx-design (for card gallery) and sphinx-copybutton. Strip commented-out dead code and LaTeX/man/Texinfo output boilerplate.
Convert MICADO, METIS, and MOSAIC readme.rst files to readme.md.
Factor out common installation boilerplate (prerequisites, pip install,
working directory setup, notebook workflow, references, contacts) into
docs/ScopeSim_guide.md, which each README includes via MyST {include}.
MOSAIC: fix stale reference to non-existent
Introduction_to_Scopesim_for_MOSAIC.ipynb (replaced with MOSAIC_demo.ipynb).
Replace the plain RST table index with a sphinx_design card grid showing the three documented ELT instruments (MICADO, METIS, MOSAIC), each with its logo, a one-line description, and a direct link to its getting-started guide. Retain a full instrument packages table below the cards.
teutoburg
force-pushed
the
docs/rtd-overhaul
branch
from
7558698 to
c03863f
Compare
teutoburg
left a comment
teutoburg
left a comment
There was a problem hiding this comment.
Yeah, as discussed on Slack, this is now fixed, so go. Ignore the one comment.
oczoske
left a comment
oczoske
left a comment
There was a problem hiding this comment.
Try to get a complete list of METIS notebooks as indicated.
There's a question about MOSAIC notebook not showing any images - has that been resolved? There are a few static images which will have to be in the right place for RTD to pick them up.
github-project-automation
Bot
moved this from 👀 Awaiting Review
to 🏗 In progress
in ScopeSim-development
teutoburg
force-pushed
the
docs/rtd-overhaul
branch
from
3938f4a to
c5fd670
Compare
|
I now replaced the tables in The toctree is currently a bit broken because some notebooks violate that rule that each notebook must have exactly one top-level heading ( Is this acceptable to you @oczoske and @astronomyk or do you feel strong attachment to the previous tables? |
github-project-automation
Bot
moved this from 🏗 In progress
to ✅ Done
in ScopeSim-development
3 participants
Summary
Brings the IRDB documentation up to the standard of SimCADO's docs, addressing feedback from the MICADO science team ahead of their first serious ScopeSim session. Follows the canonical A* Vienna docs template (
scopesim-targets) and the approach outlined by @teutoburg.nbsphinx. Config rewritten from scratch based on thescopesim-targetsbaseline — drops ~200 lines of commented-out dead code.docs/ScopeSim_guide.mdfactors out the boilerplate that was copy-pasted across all three instrument READMEs (prerequisites, pip install, working directory setup, running notebooks, references, contact). Each README now{include}s it — one place to maintain.readme.rst→readme.md— converted to MyST markdown, instrument-specific content kept, shared content included. MOSAIC: fixes stale reference to a non-existentIntroduction_to_Scopesim_for_MOSAIC.ipynb.index.rst→index.md— replaces the plain RST table with asphinx_designcard gallery (logo + description + link for each documented instrument).Notebooks
Notebooks remain as
.ipynb— no conversion in this PR, per the agreed scope.Test plan
Open issues
To be tackled separately, but just so it's noted somewhere:
.mdfiles, even though they work just fine in the built documentation. Disabled for now to avoid failures all the time. Should be investigated how to deal with relative links.