Skip to content

Commit

Permalink
Update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
leroyvn committed Feb 25, 2024
1 parent e7911a7 commit 1cee19d
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 66 deletions.
23 changes: 14 additions & 9 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -10,23 +10,28 @@ Dessine-moi

*Dessine-moi* v\ |release|.

.. image:: https://img.shields.io/pypi/v/dessinemoi?color=blue&style=flat-square
.. image:: https://img.shields.io/pypi/v/dessinemoi?color=blue
:target: https://pypi.org/project/dessinemoi

.. image:: https://img.shields.io/conda/v/eradiate/dessinemoi?color=blue&style=flat-square
.. image:: https://img.shields.io/conda/v/eradiate/dessinemoi?color=blue
:target: https://anaconda.org/eradiate/dessinemoi

.. image:: https://img.shields.io/github/actions/workflow/status/leroyvn/dessinemoi/ci.yml?branch=main&style=flat-square
.. image:: https://img.shields.io/github/actions/workflow/status/leroyvn/dessinemoi/ci.yml?branch=main
:target: https://github.com/leroyvn/dessinemoi/actions/workflows/ci.yml

.. image:: https://img.shields.io/readthedocs/dessinemoi?style=flat-square
.. image:: https://img.shields.io/readthedocs/dessinemoi
:target: https://dessinemoi.readthedocs.io

.. image:: https://img.shields.io/badge/code%20style-black-black?style=flat-square
:target: https://github.com/psf/black
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/mitsuhiko/rye/main/artwork/badge.json
:target: https://rye-up.com
:alt: Rye

.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
:target: https://github.com/astral-sh/ruff
:alt: Ruff

.. image:: https://img.shields.io/badge/%20imports-isort-blue?style=flat-square&labelColor=orange
:target: https://pycqa.github.io/isort
.. image:: https://img.shields.io/badge/code%20style-black-black
:target: https://github.com/psf/black

*S'il vous plaît, dessine-moi un mouton.*

Expand All @@ -49,7 +54,7 @@ Features
Getting started
---------------

*Dessine-moi* requires Python 3.7+ and depends on ``attrs``. It is tested with
*Dessine-moi* requires Python 3.8+ and depends on ``attrs``. It is tested with
Pytest.

Install from PyPI in your virtual environment:
Expand Down
76 changes: 19 additions & 57 deletions docs/src/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,83 +4,45 @@

### Requirements

Developing requires:
Developing requires:

* the [PDM](https://pdm.fming.dev/) package manager (typically installed with
[pipx](https://pypa.github.io/pipx/));
* [Nox](https://nox.thea.codes/), a test automation framework which uses Python files
for configuration.
* the [Rye](https://rye-up.com/) package manager;
* the [pre-commit](https://pre-commit.com/) git hook manager, typically
installed with [pipx](https://pipx.pypa.io/stable/).

### IDE configuration
### Setting up a development environment

Follow [instructions from the PDM documentation](https://pdm.fming.dev/#use-with-ide).

### Running tests

The testing process of Dessine-moi uses [pytest](https://docs.pytest.org)
and [Nox](https://nox.thea.codes). Two make targets are defined to help you run
the tests:

* `make test`: run pytest without creating a new environment (uses equivalent
to `nox --no-venv`);
* `make nox-test`: run pytest in a virtual environment for each selected Python
version.

### Virtual environment issues

This project uses PDM's PEP 582 support, meaning that it does not require using
a virtual environment for development.

````{warning}
We recommend [deactivating Conda's `base` environment](https://stackoverflow.com/a/54560785/3645374)
if you don't want to use a virtual environment and instead rely on PDM's PEP
582 support.
````

You may however use one if that suits you: in that case, you'll want to
configure PDM so as to use the current virtual environment as
[instructed in the PDM docs](https://pdm.fming.dev/usage/project/#working-with-a-virtualenv):
Clone the repository:

```bash
pdm config --local use_venv true
git clone [email protected]:rayference/dessinemoi.git
```

### Using a Conda virtual environment

Developing Dessine-moi using a Conda virtual environment is supported.
To get started, initialise an empty Conda environment:
Enter the created repository and set up the development environment:

```bash
conda create --name dessinemoi
cd dessinemoi
rye sync
```

Then activate it and initialise it:
Finally, activate the pre-commit hooks:

```bash
conda activate dessinemoi
make conda-init
```

```{note}
Initialisation is possible only if a conda-lock file
`requirements/conda-lock.yml` already exists. If not, you first have to generate
it using conda-lock (see [Managing dependencies](managing_dependencies)).
pre-commit install
```

(managing_dependencies)=
## Managing dependencies
### Running tests

Dependencies are managed using PDM.
The [conda-lock](https://conda-incubator.github.io/conda-lock/) utility is also
configured to help create reproducible Conda lock environments. For simplicity,
dedicated Make targets lock PDM, Conda or both environments:
The testing process of *Dessine-moi* uses [pytest](https://docs.pytest.org). A Make target is defined to
help you run the tests:

```bash
make pdm-lock # lock PDM dependencies
make conda-lock # lock Conda dependencies
make lock # chains PDM and Conda locking
make test
```

This will run pytest for all relevant files (unit tests and doctests included
in the documentation).

## Building the documentation

To build the documentation, use the dedicated Make target:
Expand Down

0 comments on commit 1cee19d

Please sign in to comment.