diff --git a/README.md b/README.md index 63a0d340..7afb46ac 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # SPARC-X-API: A Python API for the SPARC-X DFT Code -[![Package](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/package.svg)](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/package.svg) + +[![Conda Version](https://img.shields.io/conda/v/conda-forge/sparc-x-api)](https://anaconda.org/conda-forge/sparc-x-api) +[![PyPI - Version](https://img.shields.io/pypi/v/sparc-x-api)](https://pypi.org/project/sparc-x-api/) [![Coverage](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/coverage.svg)](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/coverage.svg) [![Unit tests for SPARC-X-API](https://github.com/SPARC-X/SPARC-X-API/actions/workflows/unit_test.yml/badge.svg)](https://github.com/SPARC-X/SPARC-X-API/actions/workflows/unit_test.yml) [![JSON-API](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/badges/badges/api_version.svg)](https://raw.githubusercontent.com/SPARC-X/SPARC-X-API/master/sparc/sparc_json_api/parameters.json) diff --git a/doc/img/screenshots/pypi_publisher_setup.png b/doc/img/screenshots/pypi_publisher_setup.png new file mode 100644 index 00000000..f2c83d89 Binary files /dev/null and b/doc/img/screenshots/pypi_publisher_setup.png differ diff --git a/doc/installation.md b/doc/installation.md index c379d829..2317e8e1 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -33,26 +33,43 @@ conda install -c conda-forge sparc-x conda activate sparc-env ``` +(pypi-install)= +### Install from [PyPI](https://pypi.org/project/sparc-x-api/) + +If you prefer using `pip` to install SPARC-X-API, there is also a +[mirror package on PyPI](https://pypi.org/project/sparc-x-api/): +```bash +python -m pip install sparc-x-api +``` + +The pseudopotential files will also be installed in this approach. If you wish to compile the SPARC C/C++ code, please refer to the [manual installation](#install-binary). + (pip-install)= -### [`pip`](https://pip.pypa.io/en/stable/cli/pip_install/) install from source +### Installing from latest source code -You can installed the SPARC-X-API from the latest commit using `pip` +The latest version of the SPARC-X-API can also be installed using `pip` from the source code on Github. ```bash python -m pip install git+https://github.com/SPARC-X/SPARC-X-API ``` -Optionally, you can download the latest SPMS pseudopotentials and unpacks the pseudopotential files into `/site-packages/sparc/psp`: + +```{note} +The pseudopotential files should be manually downloaded in this case. +``` + +You can download the latest SPMS pseudopotentials and unpacks the pseudopotential files into `/site-packages/sparc/psp`: ```bash python -m sparc.download_data ``` + For developers, please check the [how to -contribute](#setting-up-environment) page for setting up a development -environment for SPARC-X-API. +contribute](#setting-up-environment) page for setting up a dev-environment for SPARC-X-API. +(install-binary)= ## Install the SPARC binary code To utilize the API for drive SPARC calculations, please following the diff --git a/doc/maintainers.md b/doc/maintainers.md index 12cfd535..a5717895 100644 --- a/doc/maintainers.md +++ b/doc/maintainers.md @@ -18,12 +18,14 @@ SPARC-X-API. Push / pull request to these branches should only be made by automa etc.) A list of svg badges can be found under `badges/` directory of this - branch. See **TODO** for how to add / modify badges to be shown in + branch. + + See **TODO** for how to add / modify badges to be shown in the README. - [`gh_pages`](https://github.com/SPARC-X/SPARC-X-API/tree/gh_pages): branch to publish the documentation site. - + ### Github Pages @@ -68,7 +70,7 @@ shown in the screenshot below: - [Unit-test workflow](https://github.com/SPARC-X/SPARC-X-API/blob/master/.github/workflows/unit_test.yml) includes several steps to run unit and coverage test. - + - The steps `Create badges` and ` Manually add git badges` defines how the status badges in `README.md` are created and pushed to the `badges` branch. @@ -76,23 +78,28 @@ shown in the screenshot below: do not use more than 4 MPI cores (may subject to changes) due to the [resource limitation](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners) of hosted runners. - + - [Publish doc pages workflow](https://github.com/SPARC-X/SPARC-X-API/blob/master/.github/workflows/publish_doc_pages.yml) - uses Sphinx to convert `doc/` to doc html files. - + uses Sphinx to convert `doc/` to doc html files. + The rendered changes will only be pushed to the `gh_pages` branch with direct commit on the master branch or after one PR is merged. - + - [Update JSON schema workflow](https://github.com/SPARC-X/SPARC-X-API/blob/master/.github/workflows/update_api.yml) updates the JSON schema file after a new release in SPARC C/C++ source code. - + The workflow is run both nightly and after normal push. Change the behavior as needed. - + +- [Publish PyPI + workflow](https://github.com/SPARC-X/SPARC-X-API/blob/master/.github/workflows/publish-pypi.yml) + package the source as `sparc-x-api` and publish on PyPI. Only + activates on new releases. + ## Deploy on conda-forge ### Managing SPARC-X-API Python Package on conda-forge @@ -112,7 +119,7 @@ a version bump, see [one example](https://github.com/conda-forge/sparc-x-api-feedstock/pull/2) for the maintainers to modify and merge. Please also ensure: -- Only the `recipe/meta.yaml` needs to be changed. +- Only the `recipe/meta.yaml` needs to be changed. - Follow the conda-forge's own [recipe standard](https://conda-forge.org/docs/maintainer/guidelines/) - Do not directly use the [`.conda/meta.yaml`](https://github.com/SPARC-X/SPARC-X-API/blob/master/.conda/meta.yaml) for conda-forge (it is designed for local packaging test) - Bump the `build.number` if you need to change the recipe YAML on the same SPARC-X-API release. @@ -129,8 +136,14 @@ several issues for future releases: ## Deploy on PyPI -**TBD** - +SPARC-X-API is deployed on PyPI under the name +[`sparc-x-api`](https://pypi.org/project/sparc-x-api/). Please contact +the current maintainer [@alchem0x2a](mailto:alchem0x2a@gmail.com) if +you wish to become a co-contributor. - +Publishing on PyPI does not require setting an API token in the CI +workflow. Instead, it uses the [OIDC +protocol](https://docs.pypi.org/trusted-publishers/) for a trusted +publisher. The current settings on PyPI are like follows: +![pypi-setting](img/screenshots/pypi_publisher_setup.png)