About DESI Data Docs

This page describes how to contribute documentation to this site, which uses mkdocs + Markdown, with source files hosted at the DESI-private repo https://github.com/desihub/desidatadocs. This page is included with the site itself so that examples can be directly rendered as they would appear in the final deployment. See here for the raw markdown that generates this page.

Getting Started

Things I did to get my laptop setup to use mkdocs:

pip install mkdocs
pip install mkdocs-material
pip install pymdown-extensions

Then to view the docs locally:

mkdocs serve

Then browse to http://127.0.0.1:8000/doc/. You can then edit files and the site automatically updates live when a source file is saved.

Or to build the site for external deployment (e.g. at NERSC on Perlmutter):

mkdocs build

That creates a site/ directory to copy to the final location. To build directly to another directory use:

mkdocs build -d another_directory

And that’s it.

Examples

Basics

mkdocs+Markdown supports basic features like italics and bold and external links. It also supports links to other pages in a nested hierarchy, and to specific subsections of the current document (e.g. code examples) or sections in other documents.

Bulleted and numbered lists

• SV1: deep observations spanning multiple nights of tiles designed with extra-broad target selection cuts for the purpose of generating truth tables and refining target selection choices.
• SV2: a mini-survey “dress rehearsal” for starting SV3
• SV3: near-final target selection observed with overlapping “rosettes” of tiles achieving nearly complete coverage of those targets in the covered areas of sky

Interleaving numbered lists with sub-bullets is a bonus that is supported by mkdocs but apparently not the default GitHub preview:

1. we did this
   • blat
   • foo
2. then that
3. then some more

I didn’t figure out how to do 2a, 2b… style number-then-letter sub-bullets.

Tables

Here’s what a table would look like:

Target class	SV1	SV2	SV3
ELG	many	a few	enormous
LRG	lots	a few	even more
QSO	123	4	566
RBG	N/A	N/A	N/A
BGS	a bunch	?	!
MWS	1	2	3

Code examples

Somewhere we’ll have tutorial code, for which we’ll want inline code like a = blat(foo) and also fenced code blocks:

import numpy as np
from desispec.io import read_spectra
sp = read_spectra('spectra-0-1234.fits')

Note that little icon in the upper right of the code block copies the block to the clipboard… a nice little feature.

Search

Speaking of nice little features, see the “Search” bar in the upper right of the page. That searches across the entire site, and comes built-in without any special config.

Admonitions

Admonitions are inline colored notes, separated from the rest of the text. They are supported by mkdocs but not the default GitHub markdown preview, so these will only look correct if you are viewing via mkdocs serve or mkdocs build but not directly from GitHub.

They are a bit fancy, but potentially useful:

Note

Don’t get carried away with admonitions. There should be more normal text than admonitions.

Danger

Beware of the ZWARN mask.

Warning

This is a warning.

Info

This is an info tag.

Todo

This is a todo admonition (looks kinda like an info item).

Blat

This is a blat tag, which I guess defaults to the “note” formatting.

You get the idea.

Formulas

We can write LaTeX formulas inline \(y = ax + b\) and also as separate blocks: $$ m = \sum_i c_i \xi_i $$

Another formula: $$ \gamma = \alpha + \beta $$

Warning

The mathjax config for rendering formulas is the most fragile piece I’ve found so far, and I needed some trial and error to get something working. The default instructions resulted in formulas with unnecessary vertical scroll bars; this config requires block formulas to come immediately after a previous paragraph with no space, e.g.

Another formula
$$
\gamma = \alpha + \beta
$$

but not

Another formula

$$
\gamma = \alpha + \beta
$$

That’s the biggest “gotcha” I’ve found so far with mkdocs. I suspect that it can be fixed with a better config and isn’t baked into the format rules, since other configs I tried didn’t have that restriction but did have the extra vertical scroll bars.

Special characters

Å is HTML for the Angstrom symbol (Å)

© is HTML for the Copyright symbol (©)

Pretty pictures

Inline pictures are easy to include:

Project layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images, directories, etc.

See the top level mkdocs.yml file for configuring the navigation bar, plugins, look-and-feel, etc.

Automatic link check

We have added an automatic link check to the GitHub Actions for this repository. When a pull request is created, the file .github/workflows/pr_linkcheck.yml will check links in the files that have been changed by the pull request. This test leverages markdown-link-check and the associated Action.

Periodically we will want to verify all the links in desidatadocs. This is relatively slow (5 to 10 minutes), so it should only run occasionally, not during rapid development. The full check is activated by including the string “All Links” in a commit message. It does not require a pull request, any push with that case-sensitive string will trigger the full check.

Finally note that the file .github/workflows/mlc_config.json contains a few exceptions such as this repository itself, which is private. Please see the links above for further details and configuration.

More information

See mkdocs.org for more details about mkdocs.