Development and documentation#
Source layout#
Folder |
Purpose |
|---|---|
|
Conversion equations and operating profiles |
|
Validation, file handling, experiments and plotting |
|
JSON scenarios and runnable analysis scripts |
|
Worked scripts executed during documentation builds |
|
Offline source-backed workflows, assumptions and reference outputs |
|
Sphinx configuration, guides and API reference |
|
Physical reference cases, integration checks and plot verification |
See CONTRIBUTING.md for the requirements when adding or changing a model.
Build the documentation locally#
python -m pip install -e '.[docs]'
sphinx-build -W --keep-going -b html docs docs/_build/html
python -m http.server 8000 --directory docs/_build/html
Open http://localhost:8000/. The documentation uses Sphinx, the PyData theme,
MyST Markdown and Sphinx-Gallery. The gallery executes the example scripts,
captures their figures and produces downloadable Python files and notebooks.
API pages import the installed package, so rebuild after changing signatures or
docstrings. Warnings and failed examples make the documentation build fail.
Generated HTML, gallery pages and execution summaries are excluded from version
control. Edit the source examples in use_cases/gallery/, not docs/gallery/.
GitHub Pages deployment#
The Documentation GitHub Actions workflow builds on pull requests and pushes to
main. Pull requests only validate the documentation. Successful builds on main
upload a Pages artifact and deploy it to the github-pages environment.
The publishing source must be GitHub Actions under repository
Settings → Pages → Build and deployment. The site URL is
julianascencio.github.io/x2power-simulator.
The workflow can also be run manually from the Actions tab on main.
Deployment permissions are limited to the deployment job: pages: write and
id-token: write. Documentation builds use read-only repository access.
Validation commands#
python -m pip install -e '.[dev,plots,docs]'
ruff check .
ruff format --check .
ty check src use_cases analysis
pytest --cov=x2power --cov-report=term-missing
sphinx-build -W --keep-going -b html docs docs/_build/html
Publishing a release#
.github/workflows/release.yml uses the same token-based PyPI publishing pattern
as OrbitalPV. It builds the wheel and source distribution, checks package metadata,
runs lint/type/coverage checks, and verifies a dependency-free clean wheel install
before uploading the exact validated artifacts.
Configure PYPI_API_TOKEN as an Actions secret for this repository or its pypi
environment. Secrets from orbital-pv are not automatically available here. The
initial upload requires a PyPI token authorized to create x2power-simulator;
a token restricted to orbital-pv cannot publish this project. After the first
upload, use a token scoped to x2power-simulator. Never commit a token.
For subsequent versions:
Update the version in
pyproject.tomlandsrc/x2power/__init__.pytogether.Merge the tested release changes into
main.Push a tag
v<version>or publish a GitHub release with that tag. The workflow rejects tags that do not match the package version.Confirm the PyPI upload job succeeds and install the version from PyPI in a fresh environment.
The workflow can also be run manually from main or a matching version tag.
The .pypi-initial-release marker triggers the first upload when merged into
main; ordinary code pushes do not publish packages. Existing filenames are
skipped to allow retrying a partial upload, but PyPI cannot replace an uploaded
file. Any changed distribution needs a new version.