diff --git a/.copier-answers.yml b/.copier-answers.yml
new file mode 100644
index 0000000..302ff21
--- /dev/null
+++ b/.copier-answers.yml
@@ -0,0 +1,20 @@
+# Changes here will be overwritten by Copier
+_commit: 5.0.2
+_src_path: https://github.com/DiamondLightSource/python-copier-template.git
+author_email: Michael.Abbott@diamond.ac.uk
+author_name: Michael Abbott
+component_lifecycle: production
+component_owner: group:default/accelerator-controls
+component_type: library
+description: A Python module designed to make it easy to build complex EPICS databases
+ by writing a Python script
+distribution_name: epicsdbbuilder
+docker: true
+docker_debug: false
+docs_type: sphinx
+git_platform: github.com
+github_org: DiamondLightSource
+package_name: epicsdbbuilder
+pypi: true
+repo_name: epicsdbbuilder
+type_checker: mypy
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..c12cce5
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,72 @@
+// For format details, see https://containers.dev/implementors/json_reference/
+{
+ "name": "Python 3 Developer Container",
+ "build": {
+ "dockerfile": "../Dockerfile",
+ "target": "developer"
+ },
+ "remoteEnv": {
+ // Allow X11 apps to run inside the container
+ "DISPLAY": "${localEnv:DISPLAY}",
+ // Put things that allow it in the persistent cache
+ "PRE_COMMIT_HOME": "/cache/pre-commit",
+ "UV_CACHE_DIR": "/cache/uv",
+ "UV_PYTHON_CACHE_DIR": "/cache/uv-python",
+ // Make a venv that is specific for this workspace path as the cache is shared
+ "UV_PROJECT_ENVIRONMENT": "/cache/venv-for${localWorkspaceFolder}",
+ // Do the equivalent of "activate" the venv so we don't have to "uv run" everything
+ "VIRTUAL_ENV": "/cache/venv-for${localWorkspaceFolder}",
+ "PATH": "/cache/venv-for${localWorkspaceFolder}/bin:${containerEnv:PATH}"
+ },
+ "customizations": {
+ "vscode": {
+ // Set *default* container specific settings.json values on container create.
+ "settings": {
+ // Use the container's python by default
+ "python.defaultInterpreterPath": "/cache/venv-for${localWorkspaceFolder}/bin/python",
+ // Don't activate the venv as it is already in the PATH
+ "python.terminal.activateEnvInCurrentTerminal": false,
+ "python.terminal.activateEnvironment": false,
+ // Workaround to prevent garbled python REPL in the terminal
+ // https://github.com/microsoft/vscode-python/issues/25505
+ "python.terminal.shellIntegration.enabled": false
+ },
+ // Add the IDs of extensions you want installed when the container is created.
+ "extensions": [
+ "ms-python.python",
+ "github.vscode-github-actions",
+ "tamasfe.even-better-toml",
+ "redhat.vscode-yaml",
+ "ryanluker.vscode-coverage-gutters",
+ "charliermarsh.ruff",
+ "ms-azuretools.vscode-docker"
+ ]
+ }
+ },
+ // Create the config folder for the bash-config feature and uv cache
+ "initializeCommand": "mkdir -p ${localEnv:HOME}/.config/terminal-config",
+ "runArgs": [
+ // Allow the container to access the host X11 display and EPICS CA
+ "--net=host",
+ // Make sure SELinux does not disable with access to host filesystems like tmp
+ "--security-opt=label=disable"
+ ],
+ "mounts": [
+ // Mount in the user terminal config folder so it can be edited
+ {
+ "source": "${localEnv:HOME}/.config/terminal-config",
+ "target": "/user-terminal-config",
+ "type": "bind"
+ },
+ // Keep a persistent cross container cache for uv, pre-commit, and the venvs
+ {
+ "source": "devcontainer-shared-cache",
+ "target": "/cache",
+ "type": "volume"
+ }
+ ],
+ // Mount the parent as /workspaces so we can pip install peers as editable
+ "workspaceMount": "source=${localWorkspaceFolder}/..,target=/workspaces,type=bind",
+ // After the container is created, recreate the venv then make pre-commit first run faster
+ "postCreateCommand": "uv venv --clear && uv sync && pre-commit install --install-hooks"
+}
diff --git a/.gitattributes b/.gitattributes
deleted file mode 100644
index 41a1393..0000000
--- a/.gitattributes
+++ /dev/null
@@ -1 +0,0 @@
-*/_version_git.py export-subst
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 0000000..a7240a1
--- /dev/null
+++ b/.github/CONTRIBUTING.md
@@ -0,0 +1,27 @@
+# Contribute to the project
+
+Contributions and issues are most welcome! All issues and pull requests are
+handled through [GitHub](https://github.com/DiamondLightSource/epicsdbbuilder/issues). Also, please check for any existing issues before
+filing a new one. If you have a great idea but it involves big changes, please
+file a ticket before making a pull request! We want to make sure you don't spend
+your time coding something that might not fit the scope of the project.
+
+## Issue or Discussion?
+
+Github also offers [discussions](https://github.com/DiamondLightSource/epicsdbbuilder/discussions) as a place to ask questions and share ideas. If
+your issue is open ended and it is not obvious when it can be "closed", please
+raise it as a discussion instead.
+
+## Code Coverage
+
+While 100% code coverage does not make a library bug-free, it significantly
+reduces the number of easily caught bugs! Please make sure coverage remains the
+same or is improved by a pull request!
+
+## Developer Information
+
+It is recommended that developers use a [vscode devcontainer](https://code.visualstudio.com/docs/devcontainers/containers). This repository contains configuration to set up a containerized development environment that suits its own needs.
+
+This project was created using the [Diamond Light Source Copier Template](https://github.com/DiamondLightSource/python-copier-template) for Python projects.
+
+For more information on common tasks like setting up a developer environment, running the tests, and setting a pre-commit hook, see the template's [How-to guides](https://diamondlightsource.github.io/python-copier-template/5.0.2/how-to.html).
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..92087f5
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,21 @@
+---
+name: Bug Report
+about: The template to use for reporting bugs and usability issues
+title: " "
+labels: 'bug'
+assignees: ''
+
+---
+
+Describe the bug, including a clear and concise description of the expected behaviour, the actual behavior and the context in which you encountered it (ideally include details of your environment).
+
+## Steps To Reproduce
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+
+## Acceptance Criteria
+- Specific criteria that will be used to judge if the issue is fixed
diff --git a/.github/ISSUE_TEMPLATE/issue.md b/.github/ISSUE_TEMPLATE/issue.md
new file mode 100644
index 0000000..52c84dd
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/issue.md
@@ -0,0 +1,13 @@
+---
+name: Issue
+about: The standard template to use for feature requests, design discussions and tasks
+title: " "
+labels: ''
+assignees: ''
+
+---
+
+A brief description of the issue, including specific stakeholders and the business case where appropriate
+
+## Acceptance Criteria
+- Specific criteria that will be used to judge if the issue is fixed
diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
new file mode 100644
index 0000000..8200afe
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
@@ -0,0 +1,8 @@
+Fixes #ISSUE
+
+### Instructions to reviewer on how to test:
+1. Do thing x
+2. Confirm thing y happens
+
+### Checks for reviewer
+- [ ] Would the PR title make sense to a user on a set of release notes
diff --git a/.github/pages/index.html b/.github/pages/index.html
index cc33127..c495f39 100644
--- a/.github/pages/index.html
+++ b/.github/pages/index.html
@@ -1,9 +1,11 @@
-
- Redirecting to master branch
+
+
+ Redirecting to main branch
-
-
-
+
+
+
+
diff --git a/.github/pages/make_switcher.py b/.github/pages/make_switcher.py
new file mode 100755
index 0000000..c06813a
--- /dev/null
+++ b/.github/pages/make_switcher.py
@@ -0,0 +1,96 @@
+"""Make switcher.json to allow docs to switch between different versions."""
+
+import json
+import logging
+from argparse import ArgumentParser
+from pathlib import Path
+from subprocess import CalledProcessError, check_output
+
+
+def report_output(stdout: bytes, label: str) -> list[str]:
+ """Print and return something received frm stdout."""
+ ret = stdout.decode().strip().split("\n")
+ print(f"{label}: {ret}")
+ return ret
+
+
+def get_branch_contents(ref: str) -> list[str]:
+ """Get the list of directories in a branch."""
+ stdout = check_output(["git", "ls-tree", "-d", "--name-only", ref])
+ return report_output(stdout, "Branch contents")
+
+
+def get_sorted_tags_list() -> list[str]:
+ """Get a list of sorted tags in descending order from the repository."""
+ stdout = check_output(["git", "tag", "-l", "--sort=-v:refname"])
+ return report_output(stdout, "Tags list")
+
+
+def get_versions(ref: str, add: str | None) -> list[str]:
+ """Generate the file containing the list of all GitHub Pages builds."""
+ # Get the directories (i.e. builds) from the GitHub Pages branch
+ try:
+ builds = set(get_branch_contents(ref))
+ except CalledProcessError:
+ builds = set()
+ logging.warning(f"Cannot get {ref} contents")
+
+ # Add and remove from the list of builds
+ if add:
+ builds.add(add)
+
+ # Get a sorted list of tags
+ tags = get_sorted_tags_list()
+
+ # Make the sorted versions list from main branches and tags
+ versions: list[str] = []
+ for version in ["master", "main"] + tags:
+ if version in builds:
+ versions.append(version)
+ builds.remove(version)
+
+ # Add in anything that is left to the bottom
+ versions += sorted(builds)
+ print(f"Sorted versions: {versions}")
+ return versions
+
+
+def write_json(path: Path, repository: str, versions: list[str]):
+ """Write the JSON switcher to path."""
+ org, repo_name = repository.split("/")
+ struct = [
+ {"version": version, "url": f"https://{org}.github.io/{repo_name}/{version}/"}
+ for version in versions
+ ]
+ text = json.dumps(struct, indent=2)
+ print(f"JSON switcher:\n{text}")
+ path.write_text(text, encoding="utf-8")
+
+
+def main(args=None):
+ """Parse args and write switcher."""
+ parser = ArgumentParser(
+ description="Make a versions.json file from gh-pages directories"
+ )
+ parser.add_argument(
+ "--add",
+ help="Add this directory to the list of existing directories",
+ )
+ parser.add_argument(
+ "repository",
+ help="The GitHub org and repository name: ORG/REPO",
+ )
+ parser.add_argument(
+ "output",
+ type=Path,
+ help="Path of write switcher.json to",
+ )
+ args = parser.parse_args(args)
+
+ # Write the versions file
+ versions = get_versions("origin/gh-pages", args.add)
+ write_json(args.output, args.repository, versions)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.github/workflows/_container.yml b/.github/workflows/_container.yml
new file mode 100644
index 0000000..c32d1ba
--- /dev/null
+++ b/.github/workflows/_container.yml
@@ -0,0 +1,64 @@
+on:
+ workflow_call:
+ inputs:
+ publish:
+ type: boolean
+ description: If true, pushes image to container registry
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v5
+ with:
+ # Need this to get version number from last tag
+ fetch-depth: 0
+
+ - name: Set up Docker Buildx
+ id: buildx
+ uses: docker/setup-buildx-action@v3
+
+ - name: Log in to GitHub Docker Registry
+ if: github.event_name != 'pull_request'
+ uses: docker/login-action@v3
+ with:
+ registry: ghcr.io
+ username: ${{ github.actor }}
+ password: ${{ secrets.GITHUB_TOKEN }}
+
+ - name: Build and export to Docker local cache
+ uses: docker/build-push-action@v6
+ env:
+ DOCKER_BUILD_RECORD_UPLOAD: false
+ with:
+ context: .
+ # Need load and tags so we can test it below
+ load: true
+ tags: tag_for_testing
+
+ - name: Test we can print the version of the installed project
+ run: docker run --rm tag_for_testing python -c "import epicsdbbuilder; print(epicsdbbuilder.__version__)"
+
+ - name: Create tags for publishing image
+ id: meta
+ uses: docker/metadata-action@v5
+ with:
+ images: ghcr.io/${{ github.repository }}
+ tags: |
+ type=ref,event=tag
+ type=raw,value=latest
+
+ - name: Push cached image to container registry
+ if: inputs.publish && github.ref_type == 'tag'
+ uses: docker/build-push-action@v6
+ env:
+ DOCKER_BUILD_RECORD_UPLOAD: false
+ # This does not build the image again, it will find the image in the
+ # Docker cache and publish it
+ with:
+ context: .
+ push: true
+ tags: ${{ steps.meta.outputs.tags }}
+ labels: ${{ steps.meta.outputs.labels }}
diff --git a/.github/workflows/_dist.yml b/.github/workflows/_dist.yml
new file mode 100644
index 0000000..d84da11
--- /dev/null
+++ b/.github/workflows/_dist.yml
@@ -0,0 +1,36 @@
+on:
+ workflow_call:
+
+jobs:
+ build:
+ runs-on: "ubuntu-latest"
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v5
+ with:
+ # Need this to get version number from last tag
+ fetch-depth: 0
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v7
+
+ - name: Build sdist and wheel
+ run: >
+ export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) &&
+ uvx --from build pyproject-build
+
+ - name: Upload sdist and wheel as artifacts
+ uses: actions/upload-artifact@v4
+ with:
+ name: dist
+ path: dist
+
+ - name: Check for packaging errors
+ run: uvx twine check --strict dist/*
+
+ - name: Install produced wheel
+ run: python -m pip install dist/*.whl
+
+ - name: Test module __version__ works using the installed wheel
+ run: python -c "import epicsdbbuilder; print(epicsdbbuilder.__version__)"
diff --git a/.github/workflows/_docs.yml b/.github/workflows/_docs.yml
new file mode 100644
index 0000000..272a30f
--- /dev/null
+++ b/.github/workflows/_docs.yml
@@ -0,0 +1,55 @@
+on:
+ workflow_call:
+
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Avoid git conflicts when tag and branch pushed at same time
+ if: github.ref_type == 'tag'
+ run: sleep 60
+
+ - name: Checkout
+ uses: actions/checkout@v5
+ with:
+ # Need this to get version number from last tag
+ fetch-depth: 0
+
+ - name: Install system packages
+ run: sudo apt-get install graphviz
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v7
+
+ - name: Build docs
+ run: uv run --locked tox -e docs
+
+ - name: Remove environment.pickle
+ run: rm build/html/.doctrees/environment.pickle
+
+ - name: Upload built docs artifact
+ uses: actions/upload-artifact@v4
+ with:
+ name: docs
+ path: build
+
+ - name: Sanitize ref name for docs version
+ run: echo "DOCS_VERSION=${GITHUB_REF_NAME//[^A-Za-z0-9._-]/_}" >> $GITHUB_ENV
+
+ - name: Move to versioned directory
+ run: mv build/html .github/pages/$DOCS_VERSION
+
+ - name: Write switcher.json
+ run: python .github/pages/make_switcher.py --add $DOCS_VERSION ${{ github.repository }} .github/pages/switcher.json
+
+ - name: Publish Docs to gh-pages
+ if: github.ref_type == 'tag' || github.ref_name == 'main'
+ # We pin to the SHA, not the tag, for security reasons.
+ # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+ uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: .github/pages
+ keep_files: true
diff --git a/.github/workflows/_pypi.yml b/.github/workflows/_pypi.yml
new file mode 100644
index 0000000..fa78b9e
--- /dev/null
+++ b/.github/workflows/_pypi.yml
@@ -0,0 +1,19 @@
+on:
+ workflow_call:
+
+jobs:
+ upload:
+ runs-on: ubuntu-latest
+ environment: release
+
+ steps:
+ - name: Download dist artifact
+ uses: actions/download-artifact@v5
+ with:
+ name: dist
+ path: dist
+
+ - name: Publish to PyPI using trusted publishing
+ uses: pypa/gh-action-pypi-publish@release/v1
+ with:
+ attestations: false
diff --git a/.github/workflows/_release.yml b/.github/workflows/_release.yml
new file mode 100644
index 0000000..15171d4
--- /dev/null
+++ b/.github/workflows/_release.yml
@@ -0,0 +1,32 @@
+on:
+ workflow_call:
+
+jobs:
+ artifacts:
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Download artifacts
+ uses: actions/download-artifact@v5
+ with:
+ merge-multiple: true
+
+ - name: Zip up docs
+ run: |
+ set -vxeuo pipefail
+ if [ -d html ]; then
+ mv html $GITHUB_REF_NAME
+ zip -r docs.zip $GITHUB_REF_NAME
+ rm -rf $GITHUB_REF_NAME
+ fi
+
+ - name: Create GitHub Release
+ # We pin to the SHA, not the tag, for security reasons.
+ # https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
+ uses: softprops/action-gh-release@6da8fa9354ddfdc4aeace5fc48d7f679b5214090 # v2.4.1
+ with:
+ prerelease: ${{ contains(github.ref_name, 'a') || contains(github.ref_name, 'b') || contains(github.ref_name, 'rc') }}
+ files: "*"
+ generate_release_notes: true
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.github/workflows/_test.yml b/.github/workflows/_test.yml
new file mode 100644
index 0000000..46cd49d
--- /dev/null
+++ b/.github/workflows/_test.yml
@@ -0,0 +1,39 @@
+on:
+ workflow_call:
+ inputs:
+ python-version:
+ type: string
+ description: The version of python to install, default is from .python-version file
+ default: ""
+ runs-on:
+ type: string
+ description: The runner to run this job on
+ required: true
+
+env:
+ # https://github.com/pytest-dev/pytest/issues/2042
+ PY_IGNORE_IMPORTMISMATCH: "1"
+ UV_PYTHON: ${{ inputs.python-version }}
+
+jobs:
+ run:
+ runs-on: ${{ inputs.runs-on }}
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v5
+ with:
+ # Need this to get version number from last tag
+ fetch-depth: 0
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v7
+
+ - name: Run tests
+ run: uv run --locked tox -e tests
+
+ - name: Upload coverage to Codecov
+ uses: codecov/codecov-action@v5
+ with:
+ name: ${{ inputs.python-version }}/${{ inputs.runs-on }}
+ files: cov.xml
diff --git a/.github/workflows/_tox.yml b/.github/workflows/_tox.yml
new file mode 100644
index 0000000..56eddd4
--- /dev/null
+++ b/.github/workflows/_tox.yml
@@ -0,0 +1,22 @@
+on:
+ workflow_call:
+ inputs:
+ tox:
+ type: string
+ description: What to run under tox
+ required: true
+
+
+jobs:
+ run:
+ runs-on: "ubuntu-latest"
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v5
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v7
+
+ - name: Run tox
+ run: uv run --locked tox -e ${{ inputs.tox }}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..9feb06d
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,59 @@
+name: CI
+
+on:
+ push:
+ branches:
+ - main
+ tags:
+ - '*'
+ pull_request:
+
+jobs:
+
+ lint:
+ uses: ./.github/workflows/_tox.yml
+ with:
+ tox: pre-commit,type-checking
+
+ test:
+ strategy:
+ matrix:
+ runs-on: ["ubuntu-latest"] # can add windows-latest, macos-latest
+ python-version: ["3.11", "3.12", "3.13"]
+ fail-fast: false
+ uses: ./.github/workflows/_test.yml
+ with:
+ runs-on: ${{ matrix.runs-on }}
+ python-version: ${{ matrix.python-version }}
+
+ container:
+ needs: test
+ if: always()
+ uses: ./.github/workflows/_container.yml
+ with:
+ publish: ${{ needs.test.result == 'success' }}
+ permissions:
+ contents: read
+ packages: write
+
+ docs:
+ uses: ./.github/workflows/_docs.yml
+ permissions:
+ contents: write
+
+ dist:
+ uses: ./.github/workflows/_dist.yml
+
+ pypi:
+ needs: [dist, test]
+ if: github.ref_type == 'tag'
+ uses: ./.github/workflows/_pypi.yml
+ permissions:
+ id-token: write
+
+ release:
+ needs: [dist, test, docs]
+ if: github.ref_type == 'tag'
+ uses: ./.github/workflows/_release.yml
+ permissions:
+ contents: write
diff --git a/.github/workflows/code.yml b/.github/workflows/code.yml
deleted file mode 100644
index 64571f0..0000000
--- a/.github/workflows/code.yml
+++ /dev/null
@@ -1,109 +0,0 @@
-name: Code CI
-
-on:
- push:
- pull_request:
-
-jobs:
- build:
- strategy:
- fail-fast: false
- matrix:
- include:
- # DLS RHEL7 legacy
- - os: ubuntu-latest
- python: "2.7"
- publish: true
- epics: "R3.14.12.7"
- # sphinx deps don't work on 2.7, so install manually
- pipenv: "--skip-lock && pipenv run pip install pytest-cov pytest-flake8"
-
- # DLS RHEL7 python3 current
- - os: ubuntu-latest
- python: "3.7"
- epics: "R3.14.12.7"
- pipenv: "--dev --deploy"
-
- # DLS RHEL7 python3 as used by pythonIoc
- - os: ubuntu-latest
- python: "3.7"
- publish: true
- pipenv: "--dev --deploy"
-
- # Other random possibilities
- - os: ubuntu-latest
- python: "3.8"
- epics: "R3.15.8"
- pipenv: "--dev --deploy"
-
- - os: ubuntu-latest
- python: "3.9"
- pipenv: "--dev --deploy"
-
- - os: windows-latest
- python: "3.7"
- pipenv: "--dev --deploy"
-
- name: ${{ matrix.os }}/${{ matrix.python }}/${{ matrix.epics }}
- runs-on: ${{ matrix.os }}
-
- steps:
- - name: Checkout Source
- uses: actions/checkout@v2
-
- - name: Set up Python ${{ matrix.python }}
- uses: actions/setup-python@v2
- with:
- python-version: ${{ matrix.python }}
-
- - name: Install EPICS Base
- if: matrix.epics
- run: |
- wget -nv https://github.com/epics-base/epics-base/archive/${{ matrix.epics }}.tar.gz
- tar -zxf ${{ matrix.epics }}.tar.gz
- make -sj -C epics-base-${{ matrix.epics }}
- echo "EPICS_BASE=`pwd`/epics-base-${{ matrix.epics }}" >> $GITHUB_ENV
-
- - name: Install Python Dependencies
- # Pin pipenv so it works on python2.7
- run: |
- pip install pipenv==2020.6.2 twine build
- pipenv install --python $(python -c 'import sys; print(sys.executable)') ${{ matrix.pipenv }} && pipenv graph
-
- - name: Install epicscorelibs
- if: ${{ ! matrix.epics }}
- run: pipenv run pip install epicscorelibs
-
- - name: Create Sdist and Wheel
- if: matrix.publish
- # Set SOURCE_DATE_EPOCH from git commit for reproducible build
- # https://reproducible-builds.org/
- # Set group writable and umask to do the same to match inside DLS
- run: |
- chmod -R g+w .
- umask 0002
- SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) python -m build --sdist --wheel
-
- - name: Run Tests
- run: pipenv run tests
-
- - name: Upload Wheel and Sdist
- if: matrix.publish
- uses: actions/upload-artifact@v2
- with:
- name: dist
- path: dist/*
-
- - name: Publish Sdist and Wheel to PyPI
- # Only once when on a tag
- if: ${{ matrix.publish && startsWith(github.ref, 'refs/tags') }}
- env:
- TWINE_USERNAME: __token__
- TWINE_PASSWORD: ${{ secrets.pypi_token }}
- run: twine upload dist/*
-
- - name: Upload coverage to Codecov
- uses: codecov/codecov-action@v1
- with:
- name: ${{ matrix.os }}/${{ matrix.python }}/${{ matrix.epics }}
- files: cov.xml
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
deleted file mode 100644
index c99bdaf..0000000
--- a/.github/workflows/docs.yml
+++ /dev/null
@@ -1,71 +0,0 @@
-name: Docs CI
-
-on:
- push:
- pull_request:
-
-jobs:
- build:
- strategy:
- matrix:
- # Whether we are building all versions of the docs, or just checking they build
- publish: ["${{ github.repository_owner == 'dls-controls' && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags')) }}"]
-
- name: "Docs CI (publish=${{ matrix.publish }})"
- runs-on: ubuntu-latest
-
- steps:
- - name: Checkout Source
- uses: actions/checkout@v2
- with:
- # require all of history to see all tagged versions' docs
- fetch-depth: 0
-
- - name: Set up Python
- uses: actions/setup-python@v2
- with:
- python-version: "3.7"
-
- - name: Install Python Dependencies
- run: |
- pip install pipenv
- pipenv install --dev --deploy --python $(which python) && pipenv graph
-
- - name: Deploy index
- if: matrix.publish
- # We pin to the SHA, not the tag, for security reasons.
- # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
- uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501 # v3.7.3
- with:
- github_token: ${{ secrets.GITHUB_TOKEN }}
- publish_dir: .github/pages
- keep_files: true
-
- - name: Checkout gh-pages
- if: matrix.publish
- # As we already did a deploy of gh-pages above, it is guaranteed to be there
- # so check it out so we can selectively build docs below
- uses: actions/checkout@v2
- with:
- ref: gh-pages
- path: build/html
-
- - name: Maybe use sphinx-multiversion
- # If we are building master or a tag we will publish
- if: matrix.publish
- # So use the args we normally pass to sphinx-build, but run sphinx-multiversion
- run: mv $(pipenv --venv)/bin/sphinx-multiversion $(pipenv --venv)/bin/sphinx-build
-
- - name: Build Docs
- run: pipenv run docs
-
- - name: Publish Docs to gh-pages
- # Only master and tags are published
- if: matrix.publish
- # We pin to the SHA, not the tag, for security reasons.
- # https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions
- uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501 # v3.7.3
- with:
- github_token: ${{ secrets.GITHUB_TOKEN }}
- publish_dir: build/html
- keep_files: true
diff --git a/.github/workflows/periodic.yml b/.github/workflows/periodic.yml
new file mode 100644
index 0000000..18b419c
--- /dev/null
+++ b/.github/workflows/periodic.yml
@@ -0,0 +1,13 @@
+name: Periodic
+
+on:
+ workflow_dispatch:
+ schedule:
+ # Run weekly to check URL links still resolve
+ - cron: "0 8 * * WED"
+
+jobs:
+ linkcheck:
+ uses: ./.github/workflows/_tox.yml
+ with:
+ tox: docs -- -b linkcheck
diff --git a/.gitignore b/.gitignore
index 5804249..0f33bf2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -22,6 +22,7 @@ var/
*.egg-info/
.installed.cfg
*.egg
+**/_version.py
# PyInstaller
# Usually these files are written by a python script from a template
@@ -41,13 +42,30 @@ htmlcov/
.cache
nosetests.xml
coverage.xml
-*,cover
-*.mypy_cache
-*.pytest_cache
cov.xml
+.pytest_cache/
+.mypy_cache/
-# DLS build dir and virtual environment
-/prefix/
-/venv/
-/lightweight-venv/
-/installed.files
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+docs/_api
+
+# PyBuilder
+target/
+
+# likely venv names
+.venv*
+venv*
+
+# further build artifacts
+lockfiles/
+
+# ruff cache
+.ruff_cache/
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
deleted file mode 100644
index 1efd502..0000000
--- a/.gitlab-ci.yml
+++ /dev/null
@@ -1,4 +0,0 @@
-include:
- - project: 'controls/reports/ci_templates'
- ref: master
- file: 'python3/dls_py3_template.yml'
diff --git a/.gitleaks.toml b/.gitleaks.toml
new file mode 100644
index 0000000..9ecf124
--- /dev/null
+++ b/.gitleaks.toml
@@ -0,0 +1,19 @@
+# This allow-list is limited to YAML/YML files to cut down SealedSecrets false positives.
+# All gitleaks default rules still apply everywhere (useDefault = true).
+# To broaden this allow-list to all files, comment out the 'paths' line below.
+
+[extend]
+useDefault = true
+
+[[rules]]
+id = "generic-api-key"
+
+# Pattern-only allowlist for long Ag… tokens in YAML
+[[rules.allowlists]]
+condition = "AND"
+regexes = [
+ # Boundary-safe Ag… token without lookarounds (RE2-safe)
+ '''(?:^|[^A-Za-z0-9+/=])(Ag[A-Za-z0-9+/]{500,}={0,2})(?:[^A-Za-z0-9+/=]|$)'''
+]
+# Limit to YAML only for now. Comment this out if you want it to apply everywhere.
+paths = ['''(?i).*\.ya?ml$''']
diff --git a/.gitremotes b/.gitremotes
deleted file mode 100644
index 9fca3ec..0000000
--- a/.gitremotes
+++ /dev/null
@@ -1,2 +0,0 @@
-github git@github.com:DiamondLightSource/epicsdbbuilder.git
-gitlab-py2 ssh://git@gitlab.diamond.ac.uk/controls/python/epicsdbbuilder.git
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 0000000..a43ed57
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,37 @@
+repos:
+ - repo: https://github.com/pre-commit/pre-commit-hooks
+ rev: v5.0.0
+ hooks:
+ - id: check-added-large-files
+ exclude: ^uv.lock
+ - id: check-yaml
+ - id: check-merge-conflict
+ - id: end-of-file-fixer
+
+ - repo: local
+ hooks:
+ - id: ruff
+ name: lint with ruff
+ language: system
+ entry: ruff check --force-exclude --fix
+ types: [python]
+ require_serial: true
+
+ - id: ruff-format
+ name: format with ruff
+ language: system
+ entry: ruff format --force-exclude
+ types: [python]
+ require_serial: true
+
+ - id: uv-sync
+ name: update uv.lock and venv
+ pass_filenames: false
+ language: system
+ entry: uv sync
+ files: ^(uv\.lock|pyproject\.toml)$
+
+ - repo: https://github.com/gitleaks/gitleaks
+ rev: v8.28.0
+ hooks:
+ - id: gitleaks
diff --git a/.python-version b/.python-version
new file mode 100644
index 0000000..2c07333
--- /dev/null
+++ b/.python-version
@@ -0,0 +1 @@
+3.11
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 0000000..933c580
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,5 @@
+{
+ "recommendations": [
+ "ms-vscode-remote.remote-containers",
+ ]
+}
diff --git a/.vscode/launch.json b/.vscode/launch.json
new file mode 100644
index 0000000..7d563e0
--- /dev/null
+++ b/.vscode/launch.json
@@ -0,0 +1,19 @@
+{
+ // Use IntelliSense to learn about possible attributes.
+ // Hover to view descriptions of existing attributes.
+ // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "name": "Debug Unit Test",
+ "type": "debugpy",
+ "request": "launch",
+ "justMyCode": false,
+ "program": "${file}",
+ "purpose": [
+ "debug-test"
+ ],
+ "console": "integratedTerminal",
+ }
+ ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..101c75f
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,12 @@
+{
+ "python.testing.unittestEnabled": false,
+ "python.testing.pytestEnabled": true,
+ "editor.formatOnSave": true,
+ "editor.codeActionsOnSave": {
+ "source.organizeImports": "explicit"
+ },
+ "files.insertFinalNewline": true,
+ "[python]": {
+ "editor.defaultFormatter": "charliermarsh.ruff",
+ },
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
new file mode 100644
index 0000000..c999e86
--- /dev/null
+++ b/.vscode/tasks.json
@@ -0,0 +1,16 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+ "version": "2.0.0",
+ "tasks": [
+ {
+ "type": "shell",
+ "label": "Tests, lint and docs",
+ "command": "tox -p",
+ "options": {
+ "cwd": "${workspaceRoot}"
+ },
+ "problemMatcher": [],
+ }
+ ]
+}
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
deleted file mode 100644
index d058262..0000000
--- a/CONTRIBUTING.rst
+++ /dev/null
@@ -1,72 +0,0 @@
-Contributing
-============
-
-Contributions and issues are most welcome! All issues and pull requests are
-handled through github on the `dls_controls repository`_. Also, please check for
-any existing issues before filing a new one. If you have a great idea but it
-involves big changes, please file a ticket before making a pull request! We
-want to make sure you don't spend your time coding something that might not fit
-the scope of the project.
-
-.. _dls_controls repository: https://github.com/DiamondLightSource/epicsdbbuilder/issues
-
-Running the tests
------------------
-
-To get the source source code and run the unit tests, run::
-
- $ git clone git://github.com/DiamondLightSource/epicsdbbuilder.git
- $ cd epicsdbbuilder
- $ pipenv install --dev
- $ pipenv run tests
-
-While 100% code coverage does not make a library bug-free, it significantly
-reduces the number of easily caught bugs! Please make sure coverage remains the
-same or is improved by a pull request!
-
-Code Styling
-------------
-
-The code in this repository conforms to standards set by the following tools:
-
-- flake8_ for style checks
-
-.. _flake8: http://flake8.pycqa.org/en/latest/
-
-These tests will be run on code when running ``pipenv run tests`` and also
-automatically at check in. Please read the tool documentation for details
-on how to fix the errors it reports.
-
-Documentation
--------------
-
-Documentation is contained in the ``docs`` directory and extracted from
-docstrings of the API.
-
-Docs follow the underlining convention::
-
- Headling 1 (page title)
- =======================
-
- Heading 2
- ---------
-
- Heading 3
- ~~~~~~~~~
-
-
-You can build the docs from the project directory by running::
-
- $ pipenv run docs
- $ firefox build/html/index.html
-
-
-Release Checklist
------------------
-
-Before a new release, please go through the following checklist:
-
-- Choose a new PEP440 compliant release number
-- Git tag the version with a message summarizing the changes
-- Push to github and the actions will make a release on pypi
-- Push to internal gitlab and do a dls-release.py of the tag
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..077948c
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,44 @@
+# The devcontainer should use the developer target and run as root with podman
+# or docker with user namespaces.
+FROM ghcr.io/diamondlightsource/ubuntu-devcontainer:noble AS developer
+
+# Add any system dependencies for the developer/build environment here
+RUN apt-get update -y && apt-get install -y --no-install-recommends \
+ graphviz \
+ && apt-get dist-clean
+
+# The build stage installs the context into the venv
+FROM developer AS build
+
+# Change the working directory to the `app` directory
+# and copy in the project
+WORKDIR /app
+COPY . /app
+RUN chmod o+wrX .
+
+# Tell uv sync to install python in a known location so we can copy it out later
+ENV UV_PYTHON_INSTALL_DIR=/python
+
+# Sync the project without its dev dependencies
+RUN --mount=type=cache,target=/root/.cache/uv \
+ uv sync --locked --no-editable --no-dev
+
+
+# The runtime stage copies the built venv into a runtime container
+FROM ubuntu:noble AS runtime
+
+# Add apt-get system dependecies for runtime here if needed
+# RUN apt-get update -y && apt-get install -y --no-install-recommends \
+# some-library \
+# && apt-get dist-clean
+
+# Copy the python installation from the build stage
+COPY --from=build /python /python
+
+# Copy the environment, but not the source code
+COPY --from=build /app/.venv /app/.venv
+ENV PATH=/app/.venv/bin:$PATH
+
+# change this entrypoint if it is not the same as the repo
+#ENTRYPOINT ["epicsdbbuilder"]
+#CMD ["--version"]
diff --git a/Makefile b/Makefile
deleted file mode 100644
index 7b323fa..0000000
--- a/Makefile
+++ /dev/null
@@ -1,31 +0,0 @@
-# Specify defaults for testing
-PREFIX := $(shell pwd)/prefix
-PYTHON = dls-python
-INSTALL_DIR = $(PREFIX)/lib/python2.7/site-packages
-SCRIPT_DIR = $(PREFIX)/bin
-MODULEVER=0.0
-
-# Override with any release info
--include Makefile.private
-
-# This is run when we type make
-dist: setup.py $(wildcard epicsdbbuilder/*) docs
- MODULEVER=$(MODULEVER) $(PYTHON) setup.py bdist_egg
- touch dist
-
-# Clean the module
-clean:
- $(PYTHON) setup.py clean
- -rm -rf build dist *egg-info installed.files
- -find -name '*.pyc' -exec rm {} \;
-
-# Install the built egg
-install: dist
- $(PYTHON) setup.py easy_install -m \
- --record=installed.files \
- --install-dir=$(INSTALL_DIR) \
- --script-dir=$(SCRIPT_DIR) dist/*.egg
-
-# Build the docs with sphinx
-docs:
- sphinx-build -EWT --keep-going docs build/html
diff --git a/Pipfile b/Pipfile
deleted file mode 100644
index b6d93b6..0000000
--- a/Pipfile
+++ /dev/null
@@ -1,26 +0,0 @@
-[[source]]
-name = "pypi"
-url = "https://pypi.org/simple"
-verify_ssl = true
-
-[dev-packages]
-# Switch to main repo after PR https://github.com/Holzhaus/sphinx-multiversion/pull/64 is merged
-sphinx-multiversion = {editable = true,git = "https://github.com/DiamondLightSource/sphinx-multiversion.git",ref = "only-arg"}
-
-# Make sure lockfile is usable on other platforms
-atomicwrites = "*"
-
-# Test and docs deps
-pytest-cov = "*"
-pytest-flake8 = "*"
-sphinx-rtd-theme = "*"
-
-[packages]
-# All other package requirements from setup.cfg
-epicsdbbuilder = {editable = true,path = "."}
-
-[scripts]
-tests = "python -m pytest"
-docs = "sphinx-build -EWT --keep-going docs build/html"
-# Delete any files that git ignore hides from us
-gitclean = "git clean -fdX"
diff --git a/Pipfile.lock b/Pipfile.lock
deleted file mode 100644
index 25a84ce..0000000
--- a/Pipfile.lock
+++ /dev/null
@@ -1,404 +0,0 @@
-{
- "_meta": {
- "hash": {
- "sha256": "440ec49dc40f84e7b23248902e0cb3d7759fb34675a28f38f395fcdd789e3fdf"
- },
- "pipfile-spec": 6,
- "requires": {},
- "sources": [
- {
- "name": "pypi",
- "url": "https://pypi.org/simple",
- "verify_ssl": true
- }
- ]
- },
- "default": {
- "epicsdbbuilder": {
- "editable": true,
- "path": "."
- }
- },
- "develop": {
- "alabaster": {
- "hashes": [
- "sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359",
- "sha256:a661d72d58e6ea8a57f7a86e37d86716863ee5e92788398526d58b26a4e4dc02"
- ],
- "version": "==0.7.12"
- },
- "atomicwrites": {
- "hashes": [
- "sha256:6d1784dea7c0c8d4a5172b6c620f40b6e4cbfdf96d783691f2e1302a7b88e197",
- "sha256:ae70396ad1a434f9c7046fd2dd196fc04b12f9e91ffb859164193be8b6168a7a"
- ],
- "index": "pypi",
- "version": "==1.4.0"
- },
- "attrs": {
- "hashes": [
- "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6",
- "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"
- ],
- "version": "==20.3.0"
- },
- "babel": {
- "hashes": [
- "sha256:ab49e12b91d937cd11f0b67cb259a57ab4ad2b59ac7a3b41d6c06c0ac5b0def9",
- "sha256:bc0c176f9f6a994582230df350aa6e05ba2ebe4b3ac317eab29d9be5d2768da0"
- ],
- "version": "==2.9.1"
- },
- "certifi": {
- "hashes": [
- "sha256:1a4995114262bffbc2413b159f2a1a480c969de6e6eb13ee966d470af86af59c",
- "sha256:719a74fb9e33b9bd44cc7f3a8d94bc35e4049deebe19ba7d8e108280cfd59830"
- ],
- "version": "==2020.12.5"
- },
- "chardet": {
- "hashes": [
- "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa",
- "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"
- ],
- "version": "==4.0.0"
- },
- "coverage": {
- "hashes": [
- "sha256:004d1880bed2d97151facef49f08e255a20ceb6f9432df75f4eef018fdd5a78c",
- "sha256:01d84219b5cdbfc8122223b39a954820929497a1cb1422824bb86b07b74594b6",
- "sha256:040af6c32813fa3eae5305d53f18875bedd079960822ef8ec067a66dd8afcd45",
- "sha256:06191eb60f8d8a5bc046f3799f8a07a2d7aefb9504b0209aff0b47298333302a",
- "sha256:13034c4409db851670bc9acd836243aeee299949bd5673e11844befcb0149f03",
- "sha256:13c4ee887eca0f4c5a247b75398d4114c37882658300e153113dafb1d76de529",
- "sha256:184a47bbe0aa6400ed2d41d8e9ed868b8205046518c52464fde713ea06e3a74a",
- "sha256:18ba8bbede96a2c3dde7b868de9dcbd55670690af0988713f0603f037848418a",
- "sha256:1aa846f56c3d49205c952d8318e76ccc2ae23303351d9270ab220004c580cfe2",
- "sha256:217658ec7187497e3f3ebd901afdca1af062b42cfe3e0dafea4cced3983739f6",
- "sha256:24d4a7de75446be83244eabbff746d66b9240ae020ced65d060815fac3423759",
- "sha256:2910f4d36a6a9b4214bb7038d537f015346f413a975d57ca6b43bf23d6563b53",
- "sha256:2949cad1c5208b8298d5686d5a85b66aae46d73eec2c3e08c817dd3513e5848a",
- "sha256:2a3859cb82dcbda1cfd3e6f71c27081d18aa251d20a17d87d26d4cd216fb0af4",
- "sha256:2cafbbb3af0733db200c9b5f798d18953b1a304d3f86a938367de1567f4b5bff",
- "sha256:2e0d881ad471768bf6e6c2bf905d183543f10098e3b3640fc029509530091502",
- "sha256:30c77c1dc9f253283e34c27935fded5015f7d1abe83bc7821680ac444eaf7793",
- "sha256:3487286bc29a5aa4b93a072e9592f22254291ce96a9fbc5251f566b6b7343cdb",
- "sha256:372da284cfd642d8e08ef606917846fa2ee350f64994bebfbd3afb0040436905",
- "sha256:41179b8a845742d1eb60449bdb2992196e211341818565abded11cfa90efb821",
- "sha256:44d654437b8ddd9eee7d1eaee28b7219bec228520ff809af170488fd2fed3e2b",
- "sha256:4a7697d8cb0f27399b0e393c0b90f0f1e40c82023ea4d45d22bce7032a5d7b81",
- "sha256:51cb9476a3987c8967ebab3f0fe144819781fca264f57f89760037a2ea191cb0",
- "sha256:52596d3d0e8bdf3af43db3e9ba8dcdaac724ba7b5ca3f6358529d56f7a166f8b",
- "sha256:53194af30d5bad77fcba80e23a1441c71abfb3e01192034f8246e0d8f99528f3",
- "sha256:5fec2d43a2cc6965edc0bb9e83e1e4b557f76f843a77a2496cbe719583ce8184",
- "sha256:6c90e11318f0d3c436a42409f2749ee1a115cd8b067d7f14c148f1ce5574d701",
- "sha256:74d881fc777ebb11c63736622b60cb9e4aee5cace591ce274fb69e582a12a61a",
- "sha256:7501140f755b725495941b43347ba8a2777407fc7f250d4f5a7d2a1050ba8e82",
- "sha256:796c9c3c79747146ebd278dbe1e5c5c05dd6b10cc3bcb8389dfdf844f3ead638",
- "sha256:869a64f53488f40fa5b5b9dcb9e9b2962a66a87dab37790f3fcfb5144b996ef5",
- "sha256:8963a499849a1fc54b35b1c9f162f4108017b2e6db2c46c1bed93a72262ed083",
- "sha256:8d0a0725ad7c1a0bcd8d1b437e191107d457e2ec1084b9f190630a4fb1af78e6",
- "sha256:900fbf7759501bc7807fd6638c947d7a831fc9fdf742dc10f02956ff7220fa90",
- "sha256:92b017ce34b68a7d67bd6d117e6d443a9bf63a2ecf8567bb3d8c6c7bc5014465",
- "sha256:970284a88b99673ccb2e4e334cfb38a10aab7cd44f7457564d11898a74b62d0a",
- "sha256:972c85d205b51e30e59525694670de6a8a89691186012535f9d7dbaa230e42c3",
- "sha256:9a1ef3b66e38ef8618ce5fdc7bea3d9f45f3624e2a66295eea5e57966c85909e",
- "sha256:af0e781009aaf59e25c5a678122391cb0f345ac0ec272c7961dc5455e1c40066",
- "sha256:b6d534e4b2ab35c9f93f46229363e17f63c53ad01330df9f2d6bd1187e5eaacf",
- "sha256:b7895207b4c843c76a25ab8c1e866261bcfe27bfaa20c192de5190121770672b",
- "sha256:c0891a6a97b09c1f3e073a890514d5012eb256845c451bd48f7968ef939bf4ae",
- "sha256:c2723d347ab06e7ddad1a58b2a821218239249a9e4365eaff6649d31180c1669",
- "sha256:d1f8bf7b90ba55699b3a5e44930e93ff0189aa27186e96071fac7dd0d06a1873",
- "sha256:d1f9ce122f83b2305592c11d64f181b87153fc2c2bbd3bb4a3dde8303cfb1a6b",
- "sha256:d314ed732c25d29775e84a960c3c60808b682c08d86602ec2c3008e1202e3bb6",
- "sha256:d636598c8305e1f90b439dbf4f66437de4a5e3c31fdf47ad29542478c8508bbb",
- "sha256:deee1077aae10d8fa88cb02c845cfba9b62c55e1183f52f6ae6a2df6a2187160",
- "sha256:ebe78fe9a0e874362175b02371bdfbee64d8edc42a044253ddf4ee7d3c15212c",
- "sha256:f030f8873312a16414c0d8e1a1ddff2d3235655a2174e3648b4fa66b3f2f1079",
- "sha256:f0b278ce10936db1a37e6954e15a3730bea96a0997c26d7fee88e6c396c2086d",
- "sha256:f11642dddbb0253cc8853254301b51390ba0081750a8ac03f20ea8103f0c56b6"
- ],
- "version": "==5.5"
- },
- "docutils": {
- "hashes": [
- "sha256:0c5b78adfbf7762415433f5515cd5c9e762339e23369dbe8000d84a4bf4ab3af",
- "sha256:c2de3a60e9e7d07be26b7f2b00ca0309c207e06c100f9cc2a94931fc75a478fc"
- ],
- "version": "==0.16"
- },
- "flake8": {
- "hashes": [
- "sha256:1aa8990be1e689d96c745c5682b687ea49f2e05a443aff1f8251092b0014e378",
- "sha256:3b9f848952dddccf635be78098ca75010f073bfe14d2c6bda867154bea728d2a"
- ],
- "version": "==3.9.1"
- },
- "idna": {
- "hashes": [
- "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6",
- "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"
- ],
- "version": "==2.10"
- },
- "imagesize": {
- "hashes": [
- "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1",
- "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"
- ],
- "version": "==1.2.0"
- },
- "importlib-metadata": {
- "hashes": [
- "sha256:8c501196e49fb9df5df43833bdb1e4328f64847763ec8a50703148b73784d581",
- "sha256:d7eb1dea6d6a6086f8be21784cc9e3bcfa55872b52309bc5fad53a8ea444465d"
- ],
- "markers": "python_version < '3.8' and python_version < '3.8'",
- "version": "==4.0.1"
- },
- "iniconfig": {
- "hashes": [
- "sha256:011e24c64b7f47f6ebd835bb12a743f2fbe9a26d4cecaa7f53bc4f35ee9da8b3",
- "sha256:bc3af051d7d14b2ee5ef9969666def0cd1a000e121eaea580d4a313df4b37f32"
- ],
- "version": "==1.1.1"
- },
- "jinja2": {
- "hashes": [
- "sha256:03e47ad063331dd6a3f04a43eddca8a966a26ba0c5b7207a9a9e4e08f1b29419",
- "sha256:a6d58433de0ae800347cab1fa3043cebbabe8baa9d29e668f1c768cb87a333c6"
- ],
- "version": "==2.11.3"
- },
- "markupsafe": {
- "hashes": [
- "sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473",
- "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161",
- "sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235",
- "sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5",
- "sha256:13d3144e1e340870b25e7b10b98d779608c02016d5184cfb9927a9f10c689f42",
- "sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff",
- "sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b",
- "sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1",
- "sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e",
- "sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183",
- "sha256:535f6fc4d397c1563d08b88e485c3496cf5784e927af890fb3c3aac7f933ec66",
- "sha256:596510de112c685489095da617b5bcbbac7dd6384aeebeda4df6025d0256a81b",
- "sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1",
- "sha256:6788b695d50a51edb699cb55e35487e430fa21f1ed838122d722e0ff0ac5ba15",
- "sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1",
- "sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e",
- "sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b",
- "sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905",
- "sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735",
- "sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d",
- "sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e",
- "sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d",
- "sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c",
- "sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21",
- "sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2",
- "sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5",
- "sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b",
- "sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6",
- "sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f",
- "sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f",
- "sha256:cdb132fc825c38e1aeec2c8aa9338310d29d337bebbd7baa06889d09a60a1fa2",
- "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7",
- "sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be"
- ],
- "version": "==1.1.1"
- },
- "mccabe": {
- "hashes": [
- "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42",
- "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f"
- ],
- "version": "==0.6.1"
- },
- "packaging": {
- "hashes": [
- "sha256:5b327ac1320dc863dca72f4514ecc086f31186744b84a230374cc1fd776feae5",
- "sha256:67714da7f7bc052e064859c05c595155bd1ee9f69f76557e21f051443c20947a"
- ],
- "version": "==20.9"
- },
- "pluggy": {
- "hashes": [
- "sha256:15b2acde666561e1298d71b523007ed7364de07029219b604cf808bfa1c765b0",
- "sha256:966c145cd83c96502c3c3868f50408687b38434af77734af1e9ca461a4081d2d"
- ],
- "version": "==0.13.1"
- },
- "py": {
- "hashes": [
- "sha256:21b81bda15b66ef5e1a777a21c4dcd9c20ad3efd0b3f817e7a809035269e1bd3",
- "sha256:3b80836aa6d1feeaa108e046da6423ab8f6ceda6468545ae8d02d9d58d18818a"
- ],
- "version": "==1.10.0"
- },
- "pycodestyle": {
- "hashes": [
- "sha256:514f76d918fcc0b55c6680472f0a37970994e07bbb80725808c17089be302068",
- "sha256:c389c1d06bf7904078ca03399a4816f974a1d590090fecea0c63ec26ebaf1cef"
- ],
- "version": "==2.7.0"
- },
- "pyflakes": {
- "hashes": [
- "sha256:7893783d01b8a89811dd72d7dfd4d84ff098e5eed95cfa8905b22bbffe52efc3",
- "sha256:f5bc8ecabc05bb9d291eb5203d6810b49040f6ff446a756326104746cc00c1db"
- ],
- "version": "==2.3.1"
- },
- "pygments": {
- "hashes": [
- "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f",
- "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e"
- ],
- "version": "==2.9.0"
- },
- "pyparsing": {
- "hashes": [
- "sha256:c203ec8783bf771a155b207279b9bccb8dea02d8f0c9e5f8ead507bc3246ecc1",
- "sha256:ef9d7589ef3c200abe66653d3f1ab1033c3c419ae9b9bdb1240a85b024efc88b"
- ],
- "version": "==2.4.7"
- },
- "pytest": {
- "hashes": [
- "sha256:671238a46e4df0f3498d1c3270e5deb9b32d25134c99b7d75370a68cfbe9b634",
- "sha256:6ad9c7bdf517a808242b998ac20063c41532a570d088d77eec1ee12b0b5574bc"
- ],
- "version": "==6.2.3"
- },
- "pytest-cov": {
- "hashes": [
- "sha256:359952d9d39b9f822d9d29324483e7ba04a3a17dd7d05aa6beb7ea01e359e5f7",
- "sha256:bdb9fdb0b85a7cc825269a4c56b48ccaa5c7e365054b6038772c32ddcdc969da"
- ],
- "index": "pypi",
- "version": "==2.11.1"
- },
- "pytest-flake8": {
- "hashes": [
- "sha256:c28cf23e7d359753c896745fd4ba859495d02e16c84bac36caa8b1eec58f5bc1",
- "sha256:f0259761a903563f33d6f099914afef339c085085e643bee8343eb323b32dd6b"
- ],
- "index": "pypi",
- "version": "==1.0.7"
- },
- "pytz": {
- "hashes": [
- "sha256:83a4a90894bf38e243cf052c8b58f381bfe9a7a483f6a9cab140bc7f702ac4da",
- "sha256:eb10ce3e7736052ed3623d49975ce333bcd712c7bb19a58b9e2089d4057d0798"
- ],
- "version": "==2021.1"
- },
- "requests": {
- "hashes": [
- "sha256:27973dd4a904a4f13b263a19c866c13b92a39ed1c964655f025f3f8d3d75b804",
- "sha256:c210084e36a42ae6b9219e00e48287def368a26d03a048ddad7bfee44f75871e"
- ],
- "version": "==2.25.1"
- },
- "snowballstemmer": {
- "hashes": [
- "sha256:b51b447bea85f9968c13b650126a888aabd4cb4463fca868ec596826325dedc2",
- "sha256:e997baa4f2e9139951b6f4c631bad912dfd3c792467e2f03d7239464af90e914"
- ],
- "version": "==2.1.0"
- },
- "sphinx": {
- "hashes": [
- "sha256:19010b7b9fa0dc7756a6e105b2aacd3a80f798af3c25c273be64d7beeb482cb1",
- "sha256:2320d4e994a191f4b4be27da514e46b3d6b420f2ff895d064f52415d342461e8"
- ],
- "version": "==3.5.4"
- },
- "sphinx-multiversion": {
- "editable": true,
- "git": "https://github.com/DiamondLightSource/sphinx-multiversion.git",
- "ref": "3e72beb7f8f0a76b53722fb2eb3daeed3d2a3d31"
- },
- "sphinx-rtd-theme": {
- "hashes": [
- "sha256:32bd3b5d13dc8186d7a42fc816a23d32e83a4827d7d9882948e7b837c232da5a",
- "sha256:4a05bdbe8b1446d77a01e20a23ebc6777c74f43237035e76be89699308987d6f"
- ],
- "index": "pypi",
- "version": "==0.5.2"
- },
- "sphinxcontrib-applehelp": {
- "hashes": [
- "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a",
- "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"
- ],
- "version": "==1.0.2"
- },
- "sphinxcontrib-devhelp": {
- "hashes": [
- "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e",
- "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"
- ],
- "version": "==1.0.2"
- },
- "sphinxcontrib-htmlhelp": {
- "hashes": [
- "sha256:3c0bc24a2c41e340ac37c85ced6dafc879ab485c095b1d65d2461ac2f7cca86f",
- "sha256:e8f5bb7e31b2dbb25b9cc435c8ab7a79787ebf7f906155729338f3156d93659b"
- ],
- "version": "==1.0.3"
- },
- "sphinxcontrib-jsmath": {
- "hashes": [
- "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
- "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
- ],
- "version": "==1.0.1"
- },
- "sphinxcontrib-qthelp": {
- "hashes": [
- "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72",
- "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"
- ],
- "version": "==1.0.3"
- },
- "sphinxcontrib-serializinghtml": {
- "hashes": [
- "sha256:eaa0eccc86e982a9b939b2b82d12cc5d013385ba5eadcc7e4fed23f4405f77bc",
- "sha256:f242a81d423f59617a8e5cf16f5d4d74e28ee9a66f9e5b637a18082991db5a9a"
- ],
- "version": "==1.1.4"
- },
- "toml": {
- "hashes": [
- "sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b",
- "sha256:b3bda1d108d5dd99f4a20d24d9c348e91c4db7ab1b749200bded2f839ccbe68f"
- ],
- "version": "==0.10.2"
- },
- "typing-extensions": {
- "hashes": [
- "sha256:0ac0f89795dd19de6b97debb0c6af1c70987fd80a2d62d1958f7e56fcc31b497",
- "sha256:50b6f157849174217d0656f99dc82fe932884fb250826c18350e159ec6cdf342",
- "sha256:779383f6086d90c99ae41cf0ff39aac8a7937a9283ce0a414e5dd782f4c94a84"
- ],
- "markers": "python_version < '3.8'",
- "version": "==3.10.0.0"
- },
- "urllib3": {
- "hashes": [
- "sha256:753a0374df26658f99d826cfe40394a686d05985786d946fbe4165b5148f5a7c",
- "sha256:a7acd0977125325f516bda9735fa7142b909a8d01e8b2e4c8108d0984e6e0098"
- ],
- "version": "==1.26.5"
- },
- "zipp": {
- "hashes": [
- "sha256:3607921face881ba3e026887d8150cca609d517579abe052ac81fc5aeffdbd76",
- "sha256:51cb66cc54621609dd593d1787f286ee42a5c0adbb4b29abea5a63edc3e03098"
- ],
- "version": "==3.4.1"
- }
- }
-}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9c326a4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+[](https://github.com/DiamondLightSource/epicsdbbuilder/actions/workflows/ci.yml)
+[](https://codecov.io/gh/DiamondLightSource/epicsdbbuilder)
+[](https://pypi.org/project/epicsdbbuilder)
+[](https://www.apache.org/licenses/LICENSE-2.0)
+
+# epicsdbbuilder
+
+This Python module is designed to make it easy to build complex EPICS databases
+by writing a Python script. While writing record templates the corresponding
+dbd entries are checked to reduce the number of errors in the database.
+
+
+Source |
+:---: | :---:
+PyPI | `pip install epicsdbbuilder`
+Docker | `docker run ghcr.io/diamondlightsource/epicsdbbuilder:latest`
+Documentation |
+Releases |
+
+A simple example of the use of this library is the following:
+
+```python
+
+ from epicsdbbuilder import *
+ InitialiseDbd('/dls_sw/epics/R3.14.12.3/base/')
+ SetTemplateRecordNames()
+
+ a = records.ao('TEST')
+ c = records.calc('CALC', CALC = 'A+B', SCAN = '1 second', INPA = a.VAL)
+ c.INPB = c
+
+ WriteRecords('output.db')
+```
+
+
+
+See https://diamondlightsource.github.io/epicsdbbuilder for more detailed documentation.
diff --git a/README.rst b/README.rst
deleted file mode 100644
index 5eae2b8..0000000
--- a/README.rst
+++ /dev/null
@@ -1,56 +0,0 @@
-EPICS Database Builder
-======================
-
-|code_ci| |docs_ci| |coverage| |pypi_version| |license|
-
-This Python module is designed to make it easy to build complex EPICS databases
-by writing a Python script. While writing record templates the corresponding
-dbd entries are checked to reduce the number of errors in the database.
-
-============== ==============================================================
-PyPI ``pip install epicsdbbuilder``
-Source code https://github.com/DiamondLightSource/epicsdbbuilder
-Documentation https://DiamondLightSource.github.io/epicsdbbuilder
-============== ==============================================================
-
-A simple example of the use of this library is the following:
-
-.. code:: python
-
- from epicsdbbuilder import *
- InitialiseDbd('/dls_sw/epics/R3.14.12.3/base/')
- SetTemplateRecordNames()
-
- a = records.ao('TEST')
- c = records.calc('CALC', CALC = 'A+B', SCAN = '1 second', INPA = a.VAL)
- c.INPB = c
-
- WriteRecords('output.db')
-
-.. |code_ci| image:: https://github.com/DiamondLightSource/epicsdbbuilder/workflows/Code%20CI/badge.svg?branch=master
- :target: https://github.com/DiamondLightSource/epicsdbbuilder/actions?query=workflow%3A%22Code+CI%22
- :alt: Code CI
-
-.. |docs_ci| image:: https://github.com/DiamondLightSource/epicsdbbuilder/workflows/Docs%20CI/badge.svg?branch=master
- :target: https://github.com/DiamondLightSource/epicsdbbuilder/actions?query=workflow%3A%22Docs+CI%22
- :alt: Docs CI
-
-.. |coverage| image:: https://codecov.io/gh/DiamondLightSource/epicsdbbuilder/branch/master/graph/badge.svg
- :target: https://codecov.io/gh/DiamondLightSource/epicsdbbuilder
- :alt: Test Coverage
-
-.. |pypi_version| image:: https://img.shields.io/pypi/v/epicsdbbuilder.svg
- :target: https://pypi.org/project/epicsdbbuilder
- :alt: Latest PyPI version
-
-.. |license| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
- :target: https://opensource.org/licenses/Apache-2.0
- :alt: Apache License
-
-..
- Anything below this line is used when viewing README.rst and will be replaced
- when included in index.rst
-
-See https://DiamondLightSource.github.io/epicsdbbuilder for more detailed documentation.
-
-
diff --git a/catalog-info.yaml b/catalog-info.yaml
new file mode 100644
index 0000000..5a50cc8
--- /dev/null
+++ b/catalog-info.yaml
@@ -0,0 +1,10 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: epicsdbbuilder
+ title: epicsdbbuilder
+ description: A Python module designed to make it easy to build complex EPICS databases by writing a Python script
+spec:
+ type: library
+ lifecycle: production
+ owner: group:default/accelerator-controls
diff --git a/docs/_templates/custom-module-template.rst b/docs/_templates/custom-module-template.rst
new file mode 100644
index 0000000..9aeca54
--- /dev/null
+++ b/docs/_templates/custom-module-template.rst
@@ -0,0 +1,37 @@
+{{ ('``' + fullname + '``') | underline }}
+
+{%- set filtered_members = [] %}
+{%- for item in members %}
+ {%- if item in functions + classes + exceptions + attributes %}
+ {% set _ = filtered_members.append(item) %}
+ {%- endif %}
+{%- endfor %}
+
+.. automodule:: {{ fullname }}
+ :members:
+
+ {% block modules %}
+ {% if modules %}
+ .. rubric:: Submodules
+
+ .. autosummary::
+ :toctree:
+ :template: custom-module-template.rst
+ :recursive:
+ {% for item in modules %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
+
+ {% block members %}
+ {% if filtered_members %}
+ .. rubric:: Members
+
+ .. autosummary::
+ :nosignatures:
+ {% for item in filtered_members %}
+ {{ item }}
+ {%- endfor %}
+ {% endif %}
+ {% endblock %}
diff --git a/docs/conf.py b/docs/conf.py
index 0e11489..d06c30b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -1,55 +1,58 @@
-# -*- coding: utf-8 -*-
-#
-# Cothread documentation build configuration file, created by
-# sphinx-quickstart on Fri May 14 13:06:33 2010.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
+"""Configuration file for the Sphinx documentation builder.
+
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
-import os
import sys
+from pathlib import Path
+from subprocess import check_output
+
+import requests
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))
-sys.path.insert(0, repo_root)
+import epicsdbbuilder
-import epicsdbbuilder # noqa
+# -- General configuration ------------------------------------------------
# General information about the project.
-project = u'EPICS Database Builder'
-copyright = u'2015, Michael Abbott'
+project = "epicsdbbuilder"
# The full version, including alpha/beta/rc tags.
release = epicsdbbuilder.__version__
# The short X.Y version.
-if '+' in release:
- # Not on a tag
- version = 'master'
+if "+" in release:
+ # Not on a tag, use branch name
+ root = Path(__file__).absolute().parent.parent
+ git_branch = check_output("git branch --show-current".split(), cwd=root)
+ version = git_branch.decode().strip()
else:
version = release
-# -- General configuration -----------------------------------------------------
-
extensions = [
+ # Use this for generating API docs
+ # "sphinx.ext.autodoc", Disabled so we can create our own API file
+ # and making summary tables at the top of API docs
+ "sphinx.ext.autosummary",
+ # This can parse google style docstrings
+ "sphinx.ext.napoleon",
# For linking to external sphinx documentation
- 'sphinx.ext.intersphinx',
+ "sphinx.ext.intersphinx",
# Add links to source code in API docs
- 'sphinx.ext.viewcode',
- # Add multiple versions of documentation on CI
- 'sphinx_multiversion',
- # Add autodoc directives
- 'sphinx.ext.autodoc',
+ "sphinx.ext.viewcode",
+ # Adds the inheritance-diagram generation directive
+ "sphinx.ext.inheritance_diagram",
+ # Add a copy button to each code block
+ "sphinx_copybutton",
+ # For the card element
+ "sphinx_design",
+ # So we can write markdown files
+ "myst_parser",
]
-viewcode_import = True
+# So we can use the ::: syntax
+myst_enable_extensions = ["colon_fence"]
# If true, Sphinx will warn about all references where the target cannot
# be found.
@@ -59,71 +62,130 @@
# generating warnings in "nitpicky mode". Note that type should include the
# domain name if present. Example entries would be ('py:func', 'int') or
# ('envvar', 'LD_LIBRARY_PATH').
-nitpick_ignore = [('py:func', 'int')]
+nitpick_ignore = [
+ ("py:class", "NoneType"),
+ ("py:class", "'str'"),
+ ("py:class", "'float'"),
+ ("py:class", "'int'"),
+ ("py:class", "'bool'"),
+ ("py:class", "'object'"),
+ ("py:class", "'id'"),
+ ("py:class", "typing_extensions.Literal"),
+]
+
+# Both the class’ and the __init__ method’s docstring are concatenated and
+# inserted into the main body of the autoclass directive
+autoclass_content = "both"
+
+# Order the members by the order they appear in the source code
+autodoc_member_order = "bysource"
+
+# Don't inherit docstrings from baseclasses
+autodoc_inherit_docstrings = False
+
+# Document only what is in __all__
+autosummary_ignore_module_all = False
# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
-# The suffix of source filenames.
-source_suffix = '.rst'
+# Output graphviz directive produced images in a scalable format
+graphviz_output_format = "svg"
-# The master toctree document.
-master_doc = 'index'
+# The name of a reST role (builtin or Sphinx extension) to use as the default
+# role, that is, for text marked up `like this`
+default_role = "any"
-# Use the Sphinx Python domain for code documentation.
-primary_domain = 'py'
+# The master toctree document.
+master_doc = "index"
-# List of directories, relative to source directory, that shouldn't be searched
-# for source files.
-exclude_trees = ['_build']
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# These patterns also affect html_static_path and html_extra_path
+exclude_patterns = ["_build"]
# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
# This means you can link things like `str` and `asyncio` to the relevant
# docs in the python documentation.
-intersphinx_mapping = dict(python=('https://docs.python.org/3/', None))
+intersphinx_mapping = {"python": ("https://docs.python.org/3/", None)}
-# -- Options for HTML output ---------------------------------------------------
+# A dictionary of graphviz graph attributes for inheritance diagrams.
+inheritance_graph_attrs = {"rankdir": "TB"}
-# The theme to use for HTML and HTML Help pages. Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-try:
- import sphinx_rtd_theme
- html_theme = 'sphinx_rtd_theme'
-except ImportError:
- html_theme = 'default'
+# Ignore localhost links for periodic check that links in docs are valid
+linkcheck_ignore = [r"http://localhost:\d+/"]
-# Options for the sphinx rtd theme, use DLS blue
-html_theme_options = dict(style_nav_header_background='rgb(7, 43, 93)')
+# Set copy-button to ignore python and bash prompts
+# https://sphinx-copybutton.readthedocs.io/en/latest/use.html#using-regexp-prompt-identifiers
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = "pydata_sphinx_theme"
+github_repo = "epicsdbbuilder"
+github_user = "DiamondLightSource"
+switcher_json = f"https://{github_user}.github.io/{github_repo}/switcher.json"
+switcher_exists = requests.get(switcher_json).ok
+if not switcher_exists:
+ print(
+ "*** Can't read version switcher, is GitHub pages enabled? \n"
+ " Once Docs CI job has successfully run once, set the "
+ "Github pages source branch to be 'gh-pages' at:\n"
+ f" https://github.com/{github_user}/{github_repo}/settings/pages",
+ file=sys.stderr,
+ )
+
+# Theme options for pydata_sphinx_theme
+# We don't check switcher because there are 3 possible states for a repo:
+# 1. New project, docs are not published so there is no switcher
+# 2. Existing project with latest copier template, switcher exists and works
+# 3. Existing project with old copier template that makes broken switcher,
+# switcher exists but is broken
+# Point 3 makes checking switcher difficult, because the updated copier template
+# will fix the switcher at the end of the docs workflow, but never gets a chance
+# to complete as the docs build warns and fails.
+html_theme_options = {
+ "logo": {
+ "text": project,
+ },
+ "use_edit_page_button": True,
+ "github_url": f"https://github.com/{github_user}/{github_repo}",
+ "icon_links": [
+ {
+ "name": "PyPI",
+ "url": f"https://pypi.org/project/{project}",
+ "icon": "fas fa-cube",
+ }
+ ],
+ "switcher": {
+ "json_url": switcher_json,
+ "version_match": version,
+ },
+ "check_switcher": False,
+ "navbar_end": ["theme-switcher", "icon-links", "version-switcher"],
+ "navigation_with_keys": False,
+}
+
+# A dictionary of values to pass into the template engine’s context for all pages
+html_context = {
+ "github_user": github_user,
+ "github_repo": github_repo,
+ "github_version": version,
+ "doc_path": "docs",
+}
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
html_show_sphinx = False
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-html_show_copyright = True
-
-# Add some CSS classes for columns and other tweaks in a custom css file
-html_css_files = ['theme_overrides.css']
+html_show_copyright = False
# Logo
-html_logo = 'images/dls-logo.svg'
-html_favicon = 'images/dls-favicon.ico'
-
-# sphinx-multiversion config
-smv_rebuild_tags = False
-smv_tag_whitelist = r'^\d+\.\d+.*$' # only document tags with form 0.9*
-smv_branch_whitelist = r'^master$' # only branch to document is master
-smv_outputdir_format = '{ref.name}'
-smv_prefer_remote_refs = False
-smv_remote_whitelist = 'origin|github'
-
-# Common links that should be available on every page
-rst_epilog = """
-.. _epicscorelibs: https://github.com/mdavidsaver/epicscorelibs
-"""
+html_logo = "images/dls-logo.svg"
+html_favicon = html_logo
diff --git a/docs/contributing.rst b/docs/contributing.rst
deleted file mode 100644
index e582053..0000000
--- a/docs/contributing.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../CONTRIBUTING.rst
diff --git a/docs/explanations.md b/docs/explanations.md
new file mode 100644
index 0000000..73ab289
--- /dev/null
+++ b/docs/explanations.md
@@ -0,0 +1,10 @@
+# Explanations
+
+Explanations of how it works and why it works that way.
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+explanations/*
+```
diff --git a/docs/explanations/decisions.md b/docs/explanations/decisions.md
new file mode 100644
index 0000000..0533b98
--- /dev/null
+++ b/docs/explanations/decisions.md
@@ -0,0 +1,12 @@
+# Architectural Decision Records
+
+Architectural decisions are made throughout a project's lifetime. As a way of keeping track of these decisions, we record these decisions in Architecture Decision Records (ADRs) listed below.
+
+```{toctree}
+:glob: true
+:maxdepth: 1
+
+decisions/*
+```
+
+For more information on ADRs see this [blog by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
diff --git a/docs/explanations/decisions/0001-record-architecture-decisions.md b/docs/explanations/decisions/0001-record-architecture-decisions.md
new file mode 100644
index 0000000..44d234e
--- /dev/null
+++ b/docs/explanations/decisions/0001-record-architecture-decisions.md
@@ -0,0 +1,18 @@
+# 1. Record architecture decisions
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. To create new ADRs we will copy and
+paste from existing ones.
diff --git a/docs/explanations/decisions/0002-switched-to-python-copier-template.md b/docs/explanations/decisions/0002-switched-to-python-copier-template.md
new file mode 100644
index 0000000..66fe5d8
--- /dev/null
+++ b/docs/explanations/decisions/0002-switched-to-python-copier-template.md
@@ -0,0 +1,28 @@
+# 2. Adopt python-copier-template for project structure
+
+## Status
+
+Accepted
+
+## Context
+
+We should use the following [python-copier-template](https://github.com/DiamondLightSource/python-copier-template).
+The template will ensure consistency in developer
+environments and package management.
+
+## Decision
+
+We have switched to using the template.
+
+## Consequences
+
+This module will use a fixed set of tools as developed in `python-copier-template`
+and can pull from this template to update the packaging to the latest techniques.
+
+As such, the developer environment may have changed, the following could be
+different:
+
+- linting
+- formatting
+- pip venv setup
+- CI/CD
diff --git a/docs/explanations/decisions/COPYME b/docs/explanations/decisions/COPYME
new file mode 100644
index 0000000..b466c79
--- /dev/null
+++ b/docs/explanations/decisions/COPYME
@@ -0,0 +1,19 @@
+# 3. Short descriptive title
+
+Date: Today's date
+
+## Status
+
+Accepted
+
+## Context
+
+Background to allow us to make the decision, to show how we arrived at our conclusions.
+
+## Decision
+
+What decision we made.
+
+## Consequences
+
+What we will do as a result of this decision.
diff --git a/docs/genindex.md b/docs/genindex.md
new file mode 100644
index 0000000..73f1191
--- /dev/null
+++ b/docs/genindex.md
@@ -0,0 +1,3 @@
+# Index
+
+
diff --git a/docs/how-to.md b/docs/how-to.md
new file mode 100644
index 0000000..6b16141
--- /dev/null
+++ b/docs/how-to.md
@@ -0,0 +1,10 @@
+# How-to Guides
+
+Practical step-by-step guides for the more experienced user.
+
+```{toctree}
+:maxdepth: 1
+:glob:
+
+how-to/*
+```
diff --git a/docs/how-to/contribute.md b/docs/how-to/contribute.md
new file mode 100644
index 0000000..6e41979
--- /dev/null
+++ b/docs/how-to/contribute.md
@@ -0,0 +1,2 @@
+```{include} ../../.github/CONTRIBUTING.md
+```
diff --git a/docs/how-to/run-container.md b/docs/how-to/run-container.md
new file mode 100644
index 0000000..9e5d66b
--- /dev/null
+++ b/docs/how-to/run-container.md
@@ -0,0 +1,14 @@
+# Run in a container
+
+Pre-built containers with epicsdbbuilder and its dependencies already
+installed are available on [Github Container Registry](https://ghcr.io/DiamondLightSource/epicsdbbuilder).
+
+## Starting the container
+
+To pull the container from github container registry and run:
+
+```
+$ docker run ghcr.io/diamondlightsource/epicsdbbuilder:latest --version
+```
+
+To get a released version, use a numbered release instead of `latest`.
diff --git a/docs/images/dls-logo.svg b/docs/images/dls-logo.svg
index 79ba266..4fcaa86 100644
--- a/docs/images/dls-logo.svg
+++ b/docs/images/dls-logo.svg
@@ -1,11 +1,11 @@
-