Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: clarify pinned dependencies with Conda #150

Merged
merged 2 commits into from
Feb 8, 2022
Merged

docs: clarify pinned dependencies with Conda #150

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
83869ca
docs: clarify pinned dependencies with Conda
redeboer Feb 8, 2022
7e196a2
docs: unfold right sidebar unto second level
redeboer Feb 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,7 @@ def fetch_logo(url: str, output_path: str) -> None:
"thebelab": True,
},
"show_navbar_depth": 2,
"show_toc_level": 2,
"theme_dev_mode": True,
}
html_title = "Quantum number conservation rules"
Expand Down
94 changes: 58 additions & 36 deletions docs/install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
[![Conda package](https://anaconda.org/conda-forge/qrules/badges/version.svg)](https://anaconda.org/conda-forge/qrules)
[![Supported Python versions](https://img.shields.io/pypi/pyversions/qrules)](https://pypi.org/project/qrules)

## Quick installation

The fastest way of installing this package is through PyPI or Conda:

:::{tabbed} PyPI
Expand All @@ -22,10 +24,17 @@ conda install -c conda-forge qrules

:::

This installs the
[latest, stable release](https://github.com/ComPWA/qrules/releases) that you
can find on the [`stable`](https://github.com/ComPWA/qrules/tree/stable)
branch.
This installs the [latest release](https://github.com/ComPWA/qrules/releases)
that you can find on the
[`stable`](https://github.com/ComPWA/qrules/tree/stable) branch.

Optionally, you can install the dependencies required for
{doc}`visualizing topologies </usage/visualize>` with the following
{ref}`optional dependency syntax <compwa-org:develop:Optional dependencies>`:

```shell
pip install qrules[viz] # installs qrules with graphviz
```

The latest version on the [`main`](https://github.com/ComPWA/qrules/tree/main)
branch can be installed as follows:
Expand All @@ -34,49 +43,62 @@ branch can be installed as follows:
python3 -m pip install git+https://github.com/ComPWA/qrules@main
```

In that case, however, we highly recommend using the more dynamic
{ref}`'editable installation' <compwa-org:develop:Editable installation>`
instead. This goes as follows:
## Editable installation

1. Get the source code:
It is highly recommend to use the more dynamic
{ref}`'editable installation' <compwa-org:develop:Editable installation>`. This
allows you to:

```shell
git clone https://github.com/ComPWA/qrules.git
cd qrules
```
- exactly
{ref}`pin all dependencies <compwa-org:develop:Pinning dependency versions>`
to a specific version, so that your work is **reproducible**.
- edit the source code of the framework and
{doc}`help improving it <compwa-org:develop>`.

2. **[Recommended]** Create a virtual environment (see
{ref}`here <compwa-org:develop:Virtual environment>`).
For this, you first need to get the source code with
[Git](https://git-scm.com):

3. Install the project as an
{ref}`'editable installation' <compwa-org:develop:Editable installation>`
and install
{ref}`additional packages <compwa-org:develop:Optional dependencies>` for
the developer:
```shell
git clone https://github.com/ComPWA/qrules.git
cd qrules
```

```shell
python3 -m pip install -e .[dev]
```
Next, you install the project in editable mode with either
[Conda](https://docs.conda.io) or [`pip`](https://pypi.org/project/pip). It's
recommended to use Conda, because this also pins the version of Python.

:::{dropdown} Pinning dependency versions
:::{tabbed} Conda

In order to install the _exact same versions_ of the dependencies with which
the framework has been tested, use the provided
[constraints files](https://pip.pypa.io/en/stable/user_guide/#constraints-files)
for the specific Python version `3.x` you are using:
```shell
conda env create
```

```shell
python3 -m pip install -c .constraints/py3.x.txt -e .[dev]
```
This installs the project in a Conda environment following the definitions in
[`environment.yml`](https://github.com/ComPWA/qrules/blob/main/environment.yml).

:::

:::{tabbed} PyPI

```{seealso}
1. **[Recommended]** Create a virtual environment with
[`venv`](https://docs.python.org/3/library/venv.html) (see
{ref}`here <compwa-org:develop:Virtual environment>`).

{ref}`develop:Pinning dependency versions`
2. Install the project as an
{ref}`'editable installation' <compwa-org:develop:Editable installation>`
with {ref}`additional packages <compwa-org:develop:Optional dependencies>`
for the developer and all dependencies pinned through
[constraints files](https://pip.pypa.io/en/stable/user_guide/#constraints-files):

```shell
python3 -m pip install -c .constraints/py3.x.txt -e .[dev]
```

:::
:::

See {ref}`compwa-org:develop:Updating` for how to update the dependencies when
new commits come in.

That's all! Have a look at the {doc}`/usage` page to try out the package. You
can also have a look at the {doc}`compwa-org:develop` page for tips on how to
work with this 'editable' developer setup!
That's all! Have a look at {doc}`/usage` to try out the package. You can also
have a look at {doc}`compwa-org:develop` for tips on how to work with this
'editable' developer setup!