Contribute to the documentation¶

This guide explains how to contribute to PERLA's documentation, including adding new notebooks and markdown pages.

Adding Notebooks to the Documentation¶

PERLA's documentation notebooks are sourced from the nomad-perovskite-solar-cells-database plugin repository. To add a new notebook:

1. Add the notebook to the source repository¶

Create your notebook in:

nomad-perovskite-solar-cells-database/src/perovskite_solar_cell_database/example_uploads/perla_notebooks/

using a pull request to the nomad-perovskite-solar-cells-database plugin repository.

Use hyphens in filenames (e.g., my-new-analysis.ipynb), not underscores.

2. Update the build script¶

Edit scripts/prepare_docs.sh and add your notebook to the NOTEBOOKS array:

NOTEBOOKS=(
    "query-perovskite-database.ipynb"
    "performance-evolution.ipynb"
    # ... existing notebooks ...
    "my-new-analysis.ipynb"  # Add your notebook here
)

Edit mkdocs.yml to include your notebook in the navigation structure:

nav:
  - Tutorials:
      - Case Studies:
          - My New Analysis: notebooks/my-new-analysis.ipynb

4. Update tests¶

Edit tests/test_links.py and add your notebook to the required_notebooks list:

required_notebooks = [
    # ... existing notebooks ...
    'my-new-analysis.ipynb',  # Add here
]

5. Test locally¶

Run the preparation script and verify the documentation builds:

./scripts/prepare_docs.sh
mkdocs serve

Then run tests to ensure everything works:

uv run pytest tests/test_links.py -v

Building the Documentation Locally¶

Prerequisites¶

Python 3.12+
UV package manager
Both perla and nomad-perovskite-solar-cells-database repositories as siblings

Repository Structure Requirements¶

Important: The prepare_docs.sh script assumes a specific local repository structure. You must have both repositories cloned as sibling directories:

your-workspace/
├── perla/                                    # This repository
└── nomad-perovskite-solar-cells-database/   # Perovskite plugin repository

To set up this structure:

Clone both repositories:

git clone https://github.com/FAIRmat-NFDI/perla.git
git clone https://github.com/FAIRmat-NFDI/nomad-perovskite-solar-cells-database.git

Ensure the nomad-perovskite-solar-cells-database repository is up to date:

cd nomad-perovskite-solar-cells-database
git pull origin main
cd ../perla

Work from within the perla repository directory

The script looks for notebooks in: - ../nomad-perovskite-solar-cells-database/src/perovskite_solar_cell_database/example_uploads/perla_notebooks/

If this path doesn't exist, the documentation build will fail.

Build and serve¶

# Prepare notebooks from source
./scripts/prepare_docs.sh

# Serve documentation locally
mkdocs serve

The documentation will be available at http://127.0.0.1:8000/

Documentation Structure¶

The documentation follows the Diátaxis framework:

Tutorials/ - Learning-oriented guides
How-to Guides/ - Task-oriented instructions
Explanation/ - Understanding-oriented discussions
Reference/ - Information-oriented technical descriptions

Notes¶

The docs/notebooks/ folder is not tracked in git - it's generated by prepare_docs.sh
Notebooks are copied during build (locally and in CI/CD)
The perovskite plugin repository is the single source of truth for notebooks
CI/CD automatically runs prepare_docs.sh before building documentation