Introduction to Sphinx

Embedding schema.org / Bioschemas metadata

Toni Hermoso Pulido

ELIXIR FAIR Training Working Group

2026-04-01

Biocore @ CRG

Bioinformatics Core Technology Unit @ CRG

Biocore team 2024{.r-stretch}

Courses

Internal and external

  • Genomics Data formats (Basic Bioinformatics)

  • Linux Containers

  • Nextflow

  • Git

  • RNAseq analyses

  • Nanopore analyses

Frameworks used

  • R Markdown

  • Jekyll

  • Sphinx (with reStructuredText)

  • Slidev - for presentations

  • PowerPoint, Google Docs, LibreOffice…

Sphinx

Documentation generator created in the context of the Python community

On top of Docutils, that allows conversion into different formats (HTML, PDF, ePub, etc.)

Sphinx - History

Versioning:

  • 0.1: March 2008

  • 9.1: December 2025

Sphinx - Features

  • Cross-referencing between documents and code

  • Automatic API documentation

  • Multiple output formats (HTML, PDF, ePub)

  • Extensible via plugins and themes

reStructuredText

Default markup language used:

Section Title
=============

This is a paragraph with **bold** and *italic* text.

.. note::
   This is a note directive.

- Item one
- Item two

`Link text <https://example.com>`_

Sphinx - Examples

Heavily used in many documentation sites:

MyST

Markdown

Why Markdown matters for documentation:

  • Widely adopted: used by GitHub, GitLab, Jupyter, and most modern platforms

  • Readable as plain text, even without rendering

  • Low barrier to entry for contributors unfamiliar with reStructuredText

  • Enables documentation to live closer to code in the same ecosystem

Markdown Example

# Title

A paragraph with **bold**, *italic*, and `inline code`.

- First item
- Second item

[Link](https://example.com)

![Image alt text](image.png)

Markdown Dialects

Not all Markdown is equal — several dialects exist:

  • CommonMark: standardised, minimal spec; the base most dialects build on

  • GitHub Flavored Markdown (GFM): adds tables, task lists, and strikethrough

  • Pandoc Markdown: rich extension set targeting multi-format conversion

  • MyST (Markedly Structured Text): designed specifically for technical and scientific documentation with Sphinx

MyST

MyST bridges Markdown and Sphinx’s full power:

  • Superset of CommonMark — any valid Markdown is valid MyST

  • Supports all Sphinx directives and roles using Markdown-friendly syntax

  • First-class support for cross-references, math, and code execution (via Jupyter)

  • Allows teams to write Sphinx documentation without learning reStructuredText

MyST Origins

  • Created by the Executable Books Project in 2020

  • Born from the need to write Sphinx documentation in Markdown for Jupyter Book

  • Maintained as part of the broader scientific and technical publishing ecosystem

  • myst-parser is the Sphinx extension that enables MyST in any Sphinx project

Migrating from reStructuredText

rst-to-myst is a tool that automates conversion of .rst files to MyST Markdown:

# Install
pip install rst-to-myst

# Convert a single file
rst2myst convert docs/index.rst

# Convert all rst files in a directory
rst2myst convert docs/**/*.rst

Output is valid MyST — directives, roles, and cross-references are all preserved.

Bioschemas Sphinx extension

Motivation

  • Simplify the process of including Schema.org or Bioschemas profiles

  • Allow embedding JSON+LD in a simpler way (YAML)

  • Enable Sphinx as a metadata-friendly framework as Jekyll or Mkdocs

Embedding

Global

Applies Bioschemas markup to every page automatically via conf.py:

extensions = [
    "sphinx_bioschemas",
    "myst_parser",
]

# List of YAML or JSON files with schema markup
bioschemas = ["bioschemas.yaml"]

Global

Example bioschemas.yaml:

"@context": https://schema.org/
"@type": LearningResource
"@id": https://example.org/docs/
name: My Documentation
description: A Sphinx-based documentation site with Bioschemas metadata
license: MIT

Page-specific

Added per page using the {bioschemas} directive — appends to global markup, does not replace it:

```{bioschemas}
:format: yaml

"@context": https://schema.org/
"@type": LearningResource
"@id": https://example.org/docs/my-page
http://purl.org/dc/terms/conformsTo:
  - "@type": CreativeWork
    "@id": https://bioschemas.org/profiles/TrainingMaterial/1.0-RELEASE
name: My Page
author:
  - "@type": Person
    name: Jane Doe
keywords: sphinx, bioschemas, FAIR
```

Page-specific

Or by pointing to an external file:

```{bioschemas} ./page-bioschemas.yaml
```

CI/CD deployment

Sphinx docs can be built and published automatically on every push:

  • Both GitHub Pages and GitLab Pages are supported

  • Triggered on changes to docs/** on main/master

CI/CD deployment

GitHub Pages

name: Deploy Sphinx documentation to Pages

on:
  push:
    branches: [main]
    paths: ['docs/**']

permissions:
  pages: write
  id-token: write

jobs:
  pages:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r docs/requirements.txt && cd docs && make html
      - uses: actions/upload-pages-artifact@v4
        with:
          path: site
      - uses: actions/deploy-pages@v4

GitLab Pages

image: python:3.12

stages: [build, deploy]

sphinx:
  stage: build
  script:
    - pip install -r docs/requirements.txt
    - cd docs && make html && cd ..
    - cp -r docs/_build/html site/latest
  artifacts:
    paths: [site]
  only: [main]

pages:
  stage: deploy
  dependencies: [sphinx]
  script:
    - mv site public
  artifacts:
    paths: [public]
  only: [main]

Test in local

conf.py and Makefile needed

pyenv virtualenv 3.12.11 my_sphinx_env

cd docs # Go to docs directory

pyenv local my_sphinx_env
pip install -r requirements.txt

make html
# Go to _build directory and check result...

Challenges & Future Work

Validation at Build Time (or CI/CD)

  • Validate YAML/JSON against Schema.org and Bioschemas profiles during make html

  • Warn or fail when required fields are missing for a given profile

  • Check that @id URIs resolve — dead metadata link detection

Richer Metadata Types

Beyond LearningResource / TrainingMaterial.

Important: integrate data and software in the same repository

  • Dataset — for data-heavy documentation sites

  • SoftwareSourceCode — for software/tool documentation

  • ComputationalWorkflow — for Nextflow, Snakemake, CWL pipeline docs

Automatic Metadata

Reduce manual effort by deriving values from the repo:

  • dateModified from the last git commit timestamp

  • version from git tags

Slides

You can also prepare slides with Sphinx!

Thanks to Reveal.js Sphinx extension

This presentation is an example. You can also embed metadata as well!

Thank you!