Source for the wiki of the Queen's University High Energy and Astroparticle Theory (QHEAT) group, built with Sphinx and hosted on Read the Docs.
The site is built automatically from the main branch, so anything merged
here goes live.
The quickest route: open the page you want on the live site and click
Edit this page in the right-hand sidebar. That takes you straight to the
GitHub editor for the corresponding .rst file.
The pages live in docs/source, with the homepage in index.rst. To add a
new page, create a new .rst file alongside the others and add its filename
to the .. toctree:: at the bottom of index.rst.
Set up a virtual environment in the repository root
python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt
Then build
cd docs make html
Open docs/build/html/index.html in a browser. You can leave that tab open
and refresh after each rebuild. make latexpdf produces a PDF instead, and
make linkcheck reports any links that have rotted.
Run deactivate to leave the virtual environment.
Beyond stock reStructuredText, these extensions are enabled:
- sphinx-design
grid/carddirectives, used for the link listings on the Websites, Software, and home pages, plus the:octicon:icon role.- sphinx-copybutton
- Adds a copy button to code blocks, stripping shell prompts.
- sphinx-togglebutton
.. dropdown::-style collapsible content.sphinx.ext.mathjax- Inline and display math, e.g.
:math:`M_{200}`.
The glossary uses Sphinx's .. glossary:: directive, so entries sort
themselves alphabetically and any page can link to one with :term:`Blazar`.
The site uses Furo, configured in
docs/source/conf.py. Colours, the logo, and the favicon live in
docs/source/_static, and the footer credit is added by the small template
override in docs/source/_templates/page.html.
The QHEAT logo is by Zac Picker.
favicon.png is cropped from the Q of the wordmark. If the logo is ever
replaced, regenerate it with
pip install pillow
python - <<'EOF'
from PIL import Image
im = Image.open("docs/source/_static/qheat-logo.png").convert("RGBA")
q = im.crop((0, 0, 620, 898))
side = max(q.size)
sq = Image.new("RGBA", (side, side), (0, 0, 0, 0))
sq.paste(q, ((side - q.size[0]) // 2, (side - q.size[1]) // 2))
sq.resize((256, 256), Image.LANCZOS).save("docs/source/_static/favicon.png")
EOF