How to Maintain#

Documentation#

Build Locally:

Users can generate documentation locally using the following steps:

  1. Install Dependencies:

pip install pipx
pipx install poetry

  1. Clone Repository:

git clone https://github.com/OpenCOMPES/sed.git

  1. Navigate to Repository:

cd sed

  1. Copy Tutorial Files:

Doing this step will slow down the build process significantly. It also requires two datasets so 20 GB of free space is required.

cp -r tutorial docs/
cp -r sed/config docs/sed

  1. Create a virtual environment:

poetry shell

  1. Install Dependencies:

poetry install --with docs

  1. Build Documentation:

poetry run sphinx-build -b html docs _build

  1. View Documentation:

Open the generated HTML documentation in the _build directory.

GitHub Workflow:

The documentation workflow is designed to automatically build and deploy documentation. Additionally, maintainers of sed repository can manually trigger the documentation workflow from the Actions tab. Here’s how the workflow works:

  1. Workflow Configuration: - The documentation workflow is triggered on push events to the main branch for specific paths and files related to documentation. - Manual execution is possible using the workflow_dispatch event from the Actions tab.

    on:
  push:
    branches: [ main ]
    paths:
      - sed/**/*
      - pyproject.toml
      - tutorial/**
      - .github/workflows/documentation.yml
  workflow_dispatch:

  2. Permissions: - The workflow sets permissions for the GITHUB_TOKEN to allow deployment to GitHub Pages. - Permissions include read access to contents and write access to pages.

    permissions:
  contents: read
  pages: write
  id-token: write

  3. Concurrent Deployment: - Only one concurrent deployment is allowed to prevent conflicts. - Future idea would be to have different deployment for different versions. - Runs queued between an in-progress run and the latest queued run are skipped.

    concurrency:
  group: "pages"
  cancel-in-progress: false

  4. Workflow Steps: - The workflow is divided into two jobs: build and deploy.

    1. Build Job: - Sets up the build environment, checks out the repository, and installs necessary dependencies using Poetry. - Installs notebook dependencies and Pandoc. - Copies tutorial files to the docs directory and removes unnecessary notebooks. - Downloads RAW data for tutorials. - Builds Sphinx documentation.

    2. Deploy Job: - Deploys the built documentation to GitHub Pages.

  5. Manual Execution: - To manually trigger the workflow, go to the Actions tab on GitHub. - Click on “Run workflow” for the “documentation” workflow.

Release#

Creating a Release

To create a release, follow these steps:

  1. Create a Git Release on Github:

    • On the “tags” page, select “releases”, and press “Draft a new release”.

    • At “choose a tag”, type in the name of the new release tag. Make sure to have a v prefix in the tag name, e.g. v0.1.10.

    • Confirm creation of the tag, and press “Generate release notes”. Edit the notes as appropriate (e.g. remove auto-generated update PRs).

    • Press “Publish release”. This will create the new tag and release entry, and issue the build and upload to PyPI.

  2. Check PyPI for the Published Package:

  3. If you don’t see update on PyPI:

    • Visit the GitHub Actions page and monitor the Release workflow (OpenCOMPES/sed).

    • Check if errors occurred during the release process.

Understanding the Release Workflow

  • Release Job:

    • This workflow is responsible for versioning and releasing the package.

    • A release job runs on every git tag push (e.g., git tag v0.1.5) and publishes the package to PyPI.

    • If the publish is successful, the version in the pyproject.toml file is updated and pushed to the main branch.

  • Prerelease Job:

    • This workflow is triggered automatically on every pull request (PR) to the main branch.

    • It increments the version number for prerelease (e.g., from 0.1.5 to 0.1.6a0 to 0.1.6a1) and publishes the package to PyPI.

    • If the publish is successful, the version in the pyproject.toml file is updated and pushed to the main branch.