You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
We've tried to simplify development as much as possible to encourage contributions from anyone with experience in Python and/or R. Following the directions on this page to get going quickly. Check-out the [development page](./development.md) for more context and details
3
+
We've tried to simplify development as much as possible to encourage contributions from anyone with experience in Python and/or R. Follow the directions on this page to get going quickly. Check-out the [development page](./development.md) for more context and details
4
4
5
5
## Quick start
6
6
7
-
1. Install `pixi`
7
+
### 1. Install `pixi`
8
8
9
9
```bash
10
10
curl -fsSL https://pixi.sh/install.sh | bash
11
11
```
12
12
13
-
2. Clone the repository and setup a development environment
13
+
### 2. Clone the repository and setup a development environment
14
14
15
15
```bash
16
16
git clone https://github.com/YOURFORK/pymer4.git
17
17
cd pymer4
18
18
pixi install
19
19
```
20
20
21
-
3. Make code/documentation changes with tests and test them
21
+
### 3. Make code/documentation changes with tests and test them
22
22
23
23
```bash
24
24
pixi run tests
25
25
```
26
26
27
-
4. Push your changes to Github and open a pull request!
27
+
### 4. Push your changes to Github and open a pull request!
28
28
29
-
## Development Tools
30
-
31
-
-`pixi` for project and environment management
32
-
-`pyproject.toml` for specifying, pip, conda, runtime, and development dependencies as well as Pixi tasks
33
-
-`conda/meta.yaml` reads from `pyproject.toml` to specify conda build instructions
34
-
-`mkdocs` for documentation
35
-
-`pytest` for testing
36
-
-`VSCode` for development
37
-
38
-
## Code Guidelines
39
-
40
-
- TODO - note `ruff`
41
-
42
-
Please use [google style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html/) for documenting all functions, methods, and classes.
43
-
44
-
Please be sure to include tests with any code submissions and verify
45
-
they pass using [pytest](https://docs.pytest.org/en/latest/). To run all
46
-
package tests you can use `pytest -s --capture=no` in the project root.
47
-
To run specific tests you can point to a file or even a test function
440](https://www.python.org/dev/peps/pep-0440/) compliant with two and
55
-
only two forms of version strings: `M.N.P` and `M.N.P.devX`. Versions
56
-
with the `.devX` designation denote development versions typically on
57
-
the `master` branch or `conda` pre-release channel.
29
+
### General Recommendations
58
30
59
-
This simplifed scheme is not illustrated in the PEP 440 examples, but if
60
-
was it would be described as \"major.minor.micro\" with development
61
-
releases. To illustrate, the version sequence would look like this:
31
+
- Please use [google style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html/) for documenting all functions, methods, and classes.
32
+
- Please make sure to follow proper PEP code-formatting. You can use `pixi run lint` to check or `pixi run lint-fix` to format your files
33
+
- Please be sure to include tests with any code submissions and verify they pass using `pixi run tests`
62
34
63
-
> ```bash
64
-
> 0.7.0
65
-
> 0.7.1.dev0
66
-
> 0.7.1.dev1
67
-
> 0.7.1
68
-
>```
69
-
70
-
The third digit(s) in the `pymer4` scheme, i.e. PEP 440 \"micro,\" are
71
-
not strictly necessary but are useful for semantically versioned
72
-
\"patch\" designations. The `.devX` extension on the other hand denotes
73
-
a sequence of incremental work in progress like the alpha, beta,
74
-
developmental, release candidate system without the alphabet soup.
75
-
76
-
## Documentation Guidelines
35
+
## Updating Documentation
77
36
78
37
Documentation is written using [`mkdocs`](https://www.mkdocs.org/) with the following plugins:
Since version `0.9.0``pymer4` uses [Pixi](https://prefix.dev/blog/pixi_for_scientists) to simplify package management, development, and testing.
4
-
Use the Development Quickstart below for the TL;DR on contributing to `pymer4`.
5
-
Otherwise, checkout the rest of this page to read more about how `pymer4` is configure with Pixi
4
+
This page provides more background details and context on how Pixi and the other packaging development tools work.
5
+
[Check-out this page](./contributing.md) if you're just interested in the TL;DR on making a contribution.
6
6
7
-
## Development Quickstart
7
+
## Overview
8
+
9
+
`pymer4` uses a single [`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) file to configure package setup and requirements instead of the traditional `setup.py` & `requirements.txt` approach. This file also contains additional instructions that specify `setuptools` as the build system as well as additional instructions for Pixi (see below) to manage environments, tasks, and additional development dependencies. While this is sufficient for building a traditional `pip`-installable Python package, `pymer4` also needs a properly configured and working R installation with particular libraries pre-installed. To accomplish this, `pymer4` is distributed as a `conda` package that's built from `conda/meta.yaml`. This file is created by reading meta-data and requirements from `pyproject.toml`.
10
+
11
+
Currently, `pymer4` uses `pyproject.toml` to specify:
12
+
13
+
-`pip` dependencies in `project.dependencies`
14
+
-`conda-forge` dependencies in `tool.pixi.dependencies`
15
+
- optional development only dependences (`conda-forge`) in `tool.pixi.featre.dev.dependencies`
16
+
- the `default` environment and make sure it includes optional dependencies
17
+
- various Pixi tasks in `tool.pixi.feature.dev.tasks`
18
+
19
+
!!! note "Note"
20
+
*We hope to replace the last step above with `pixi build` when it [comes out of beta](https://pixi.sh/latest/build/getting_started/) and integrates with `rattler-build`, a replacement for `conda-build`*
21
+
22
+
## Pixi
23
+
24
+
[Pixi](https://prefix.dev/blog/pixi_for_scientists) is a modern, extremely fast project-management tool that excels at handling Python environments with mixed dependecies from `conda` and `pip`, while building upon Python standards. In other words using Pixi, **the `pyproject.tml` acts as a single source of truth for *all* of pymer4's dependencies**, including both Python and R packages.
25
+
26
+
Pixi manages projects in a style similar to popuar Javascript tools like `npm` rather than traditional Anaconda environments and is powered by extremely fast tooling like Rust, `uv` for `pip` packages, and `mamba` for `conda` packages. Using `pixi install`, Pixi creates 1 or more environments in a hidden `.pixi` folder that are *automatically* used for running a variety of [tasks](https://pixi.sh/latest/features/advanced_tasks/), short commands that can be executed with `pixi run taskName` similar to a `Makefile`. These environments are **completeley isolated** just like traditional `conda` environments, but you don't need to manage or switch to them; Pixi handles all that for you based on the configuration in `pyproject.toml`
27
+
28
+
### Tasks
29
+
30
+
Pixi also allows us to define handy commands (like a `Makefile`) that it calls *tasks*. You can see all the ones we've setup using `pixi task list` and run one with `pixi run *cmd*`. We've configured several to make it super easy to run tests, build documentation, and build the conda package itself. Running a task will automatically run it in environment for the project without you having to activate or deactivate anything. You can try them out for yourself as you're working with the code base.
31
+
32
+
### Traditional environment activation
33
+
When you ran `pixi install` Pixi created an isolated environment with all the dependencies listed in `pyproject.toml`. You can activate this environment conda-style using `pix shell` after which commands like `jupyter-book` or `pytest` will become available in your terminal. This is similar to using `conda activate *my_environment*`
Installing Pixi is very easy as it has no dependencies and doesn't affect any other Python versions or tools you may already use (e.g. Anaconda). Just copy the following command into your terminal:
Then clone the repository and run `pixi install` which will configure and create an isolated development environment for you. Once you're setup you can use any of the Pixi tasks we've configured to run tests, build docs, etc or use the Pixi cheatsheet to add/remove dependencies:
16
50
17
-
### Helpful development commands (Pixi tasks)
51
+
### Configured Tasks
52
+
53
+
The following tasks have already been configured in `pyproject.toml` and can be utilized with `pixi run taskName`
18
54
19
55
| Pixi Command | Description |
20
56
|--------------|------------------|
@@ -31,7 +67,9 @@ Then clone the repository and run `pixi install` which will configure and create
31
67
|`pixi run upload-pre`| Uploads built package to `pre-release` label; requires `$token` and `$file` environment variables to be set |
32
68
|`pixi run main`| Uploads built package to `main` label; requires `$token` and `$file` environment variables to be set |
33
69
34
-
### Pixi Cheatsheet
70
+
### Additional Commands
71
+
72
+
You can perform additional actions like adding/removing packages or activating the pixi environment with the following commands:
@@ -43,69 +81,23 @@ Then clone the repository and run `pixi install` which will configure and create
43
81
|`pixi run task_name`|`conda run -n env_name command`| Runs a command in the project environment |
44
82
|`pixi shell`|`conda activate env_name`| Activates the project environment |
45
83
46
-
## Overview
47
-
48
-
`pymer4` uses a single [`pyproject.toml`](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) file to configure package setup and requirements instead of the traditional `setup.py` & `requirements.txt` approach. This file also contains additional instructions that specify `setuptools` as the build system as well as additional instructions for Pixi (see below) to manage environments, tasks, and additional development dependencies. While this is sufficient for building a traditional `pip`-installable Python package, `pymer4` also needs a properly configured and working R installation with particular libraries pre-installed. To accomplish this, `pymer4` is distributed as a `conda` package that's built from `conda/meta.yaml`. This file is created by reading meta-data and requirements from `pyproject.toml`.
49
-
50
-
### Dependencies & Configuration
51
-
52
-
Currently, `pymer4` uses `pyproject.toml` to specify:
53
-
-`pip` dependencies in `project.dependencies`
54
-
-`conda-forge` dependencies in `tool.pixi.dependencies`
55
-
- optional development only dependences (`conda-forge`) in `tool.pixi.featre.dev.dependencies`
56
-
- the `default` environment and make sure it includes optional dependencies
57
-
- various Pixi tasks in `tool.pixi.feature.dev.tasks`
58
-
59
-
```{note}
60
-
*We hope to replace the last step above with `pixi build` when it [comes out of beta](https://pixi.sh/latest/build/getting_started/) and integrates with `rattler-build`, a replacement for `conda-build`*
61
-
```
62
-
63
-
### Automatic Testing and Deployment
84
+
## Automatic Testing and Deployment
64
85
65
86
Automated package testing and deployment are handled by a single `pixi.yml` Github Actions (GA) workflow that does the following:
87
+
66
88
- Setup up Pixi
67
89
- Configure an environment and install runtime & development depenencies
68
90
- Runs tests using `pixi run tests`
69
91
- Build and deploys docs using `pixi run docs-build`
70
92
- Build and deploys the package to the `pre-release` or `main` labels on the `ejolly` channel at Anaconda.org using `conda-build` and `anaconda-client`
71
93
72
94
A few other notes about automation & deployment
95
+
73
96
- Conda packages are exclusively `noarch` builds that should run be cross-compatible for macOS & Linux as long as the minimum required Python version is met (Windows not officially supported)
74
97
- The configured GA workflow automatically runs on any commits/PRs against the `main` branch as well as on a weekly schedule every Sunday
75
98
- Built packages are available on the `ejolly` channel on [Anaconda.org](https://anaconda.org/ejolly/pymer4) under one of the 2 following *labels*
76
99
-`main`: built from official Github Release only
77
100
-`pre-release`: built from every new commit to the `main` branch on github
78
101
79
-
```{note}
80
-
*We hope to have `pymer4` available on the `conda-forge` channel instead of `ejolly` soon!*
All documentation is built using [jupyter book](https://jupyterbook.org/en/stable/intro.html). This is handled automatically on Github Actions or you can use the Pixi tasks noted above to build the docs locally: `pixi run docs-build` and `pixi run docs-preview`
88
-
89
-
Aside from the `api.md` file which uses special directives to automatically extract function and method docstrings, new documentation can be easily added by create new markdown files or jupyter notebooks and adding them to `_toc.yml`
90
-
91
-
## Pixi
92
-
93
-
[Pixi](https://prefix.dev/blog/pixi_for_scientists) is a modern, extremely fast project-management tool that excels at handling Python environments with mixed dependecies from `conda` and `pip`, while building upon Python standards. In other words using Pixi, **the `pyproject.tml` acts as a single source of truth for *all* of pymer4's dependencies**, including both Python and R packages.
94
-
95
-
Pixi manages projects in a style similar to popuar Javascript tools like `npm` rather than traditional Anaconda environments and is powered by extremely fast tooling like Rust, `uv` for `pip` packages, and `mamba` for `conda` packages. Using `pixi install`, Pixi creates 1 or more environments in a hidden `.pixi` folder that are *automatically* used for running a variety of [tasks](https://pixi.sh/latest/features/advanced_tasks/), short commands that can be executed with `pixi run taskName` similar to a `Makefile`. These environments are **completeley isolated** just like traditional `conda` environments, but you don't need to manage or switch to them; Pixi handles all that for you based on the configuration in `pyproject.toml`
96
-
97
-
### Tasks
98
-
99
-
Pixi also allows us to define handy commands (like a `Makefile`) that it calls *tasks*. You can see all the ones we've setup using `pixi task list` and run one with `pixi run *cmd*`. We've configured several to make it super easy to run tests, build documentation, and build the conda package itself. Running a task will automatically run it in environment for the project without you having to activate or deactivate anything. You can try them out for yourself as you're working with the code base.
100
-
101
-
### Traditional environment activation
102
-
When you ran `pixi install` Pixi created an isolated environment with all the dependencies listed in `pyproject.toml`. You can activate this environment conda-style using `pix shell` after which commands like `jupyter-book` or `pytest` will become available in your terminal. This is similar to using `conda activate *my_environment*`
Copy file name to clipboardexpand all lines: docs/installation.md
+5-3
Original file line number
Diff line number
Diff line change
@@ -1,9 +1,11 @@
1
1
# Installation
2
2
3
-
!!! warning "Note"
4
-
3
+
!!! warning "**Do NOT install** using `pip`"
5
4
Due to the cross-language nature of `pymer4`, installing via `pip` is **not supported**.
6
-
You **must** install `pymer4` using `conda` or `pixi` as outlined below
5
+
You **must** install `pymer4` using `conda` as outlined below
6
+
7
+
!!! Info "Windows Users"
8
+
Unfortunately, Windows it **not officially support** as package installation can be unreliable. We recommend using the [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) and setting up a conda install through there.
0 commit comments