Skip to content

docs: add Conda-Forge and Pixi installation options #98

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

Merged
mikeqfu merged 4 commits into from
Sep 14, 2026
Merged

docs: add Conda-Forge and Pixi installation options #98

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5f3fbce
docs(readme): add pixi and conda-forge options
mikeqfu Sep 13, 2026
14cfc37
docs: align rst installation guide with readme
mikeqfu Sep 13, 2026
d7cb347
build(deps): upgrade all dependencies in uv.lock
mikeqfu Sep 13, 2026
46692de
docs: align badges in index.rst with readme
mikeqfu Sep 14, 2026
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
67 changes: 47 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,72 +2,99 @@

*An open-source tool for collecting railway codes used in different UK rail industry systems.*

[![PyPI Release Version](https://img.shields.io/pypi/v/pyrcs)](https://pypi.org/project/pyrcs/)
[![Python Version](https://img.shields.io/pypi/pyversions/pyrcs)](https://docs.python.org/3/)
[![PyPI Version](https://img.shields.io/pypi/v/pyrcs?logo=pypi)](https://pypi.org/project/pyrcs/)
[![Conda-Forge Version](https://img.shields.io/conda/vn/conda-forge/pyrcs?logo=anaconda)](https://anaconda.org/channels/conda-forge/packages/pyrcs/overview)
[![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmikeqfu%2Fpyrcs%2Frefs%2Fheads%2Fmaster%2Fpyproject.toml)](https://www.python.org/downloads/)
[![License](https://img.shields.io/github/license/mikeqfu/pyrcs)](https://github.com/mikeqfu/pyrcs/blob/master/LICENSE)
[![ReadTheDocs Documentation](https://img.shields.io/readthedocs/pyrcs?logo=readthedocs)](https://pyrcs.readthedocs.io/en/latest/?badge=latest)
[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/mikeqfu/pyrcs/github-pages.yml?logo=github&branch=master)](https://github.com/mikeqfu/pyrcs/actions)
[![Codacy - Code Quality](https://app.codacy.com/project/badge/Grade/7369679225b14eaeb92ba40c12c339d5)](https://app.codacy.com/gh/mikeqfu/pyrcs/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
[![Codecov - Test Coverage](https://codecov.io/gh/mikeqfu/pyrcs/graph/badge.svg?token=6CKN8T1RVL)](https://codecov.io/gh/mikeqfu/pyrcs)
[![DOI](https://img.shields.io/badge/10.5281%2Fzenodo.4026744-blue?label=doi)](https://doi.org/10.5281/zenodo.4026744)

PyRCS is an open-source Python package that simplifies the collection and management of railway codes used across different systems in the UK rail industry. It provides a practical toolkit for researchers, practitioners and frequent users of the [Railway Codes](http://www.railwaycodes.org.uk/index.shtml) website who work extensively with railway codes in the UK. By leveraging Python's capabilities, PyRCS enables efficient access, retrieval and manipulation of railway code data, enhancing productivity and effectiveness in working with these codes.
PyRCS is an open-source Python package that simplifies the collection and management of railway codes used across different systems in the UK rail industry. It provides a practical toolkit for researchers, practitioners and frequent users of the [Railway Codes](http://www.railwaycodes.org.uk/index.shtml) website who work extensively with railway codes in the UK. By leveraging Python's capabilities, PyRCS enables efficient access, retrieval and manipulation of railway code data, enhancing productivity and effectiveness in working with these codes.

During [installation](https://pyrcs.readthedocs.io/en/latest/installation.html), PyRCS includes a set of pre-packaged data. When users request data from a specific category on the [Railway Codes](http://www.railwaycodes.org.uk/index.shtml) website, PyRCS loads the corresponding pre-packaged data for that category by default. Additionally, it provides functionality for direct access to the latest data from the source website, ensuring users stay up to date. Users can also update the pre-packaged data as needed, keeping their resources synchronised with the latest developments.
During [installation](https://pyrcs.readthedocs.io/en/latest/installation.html), PyRCS includes a set of pre-packaged data. When users request data from a specific category on the [Railway Codes](http://www.railwaycodes.org.uk/index.shtml) website, PyRCS loads the corresponding pre-packaged data for that category by default. Additionally, it provides functionality for direct access to the latest data from the source website, ensuring users stay up to date. Users can also update the pre-packaged data as needed, keeping their resources synchronised with the latest developments.

With PyRCS, users can leverage Python's power to streamline workflows and enhance productivity when working with railway codes in the UK rail industry.
With PyRCS, users can leverage Python's power to streamline workflows and enhance productivity when working with railway codes in the UK rail industry.

## Installation

PyRCS can be installed using [`uv`](https://docs.astral.sh/uv/) (recommended) or [`pip`](https://pip.pypa.io/en/stable/cli/pip/).
PyRCS can be installed using [`uv`](https://docs.astral.sh/uv/) (recommended for speed, reliability and modern dependency resolution), [`conda-forge`](https://anaconda.org/channels/conda-forge/packages/pyrcs/overview) (including [`pixi`](https://pixi.sh/)) or traditional [`pip`](https://pip.pypa.io/en/stable/cli/pip/).

<details open>
<summary><b>Using <code>uv</code> (Recommended)</b></summary>

To add PyRCS to an existing project:
To add PyRCS to an existing project managed by [`uv`](https://docs.astral.sh/uv/):

```bash
uv add pyrcs
```

If you are working in an activated virtual environment:
If you are working in an activated virtual environment:

```bash
uv pip install --upgrade pyrcs
```
</details>

<details>
<summary><b>Using <code>pixi</code></b></summary>

To add PyRCS to a workspace using [`pixi`](https://pixi.sh/):

```bash
pixi add pyrcs
```

Alternatively, to install PyRCS from PyPI inside a `pixi` project:

```bash
pixi add --pypi pyrcs
```
</details>

<details>
<summary><b>Using pip</b></summary>
<summary><b>Using <code>pip</code></b></summary>

If you prefer standard Python packaging tools, ensure your `virtual environment`_ is activated:
To install PyRCS into an active environment using [`pip`](https://pip.pypa.io/en/stable/cli/pip/):

```bash
pip install --upgrade pyrcs
```

</details>

For detailed options, development setup and Windows troubleshooting (e.g. installing C-extension wheels), see the full [Installation Guide](https://pyrcs.readthedocs.io/en/latest/installation.html).
<details>
<summary><b>Using <code>conda</code></b></summary>

To install PyRCS into an active environment using [`conda`](https://docs.conda.io/) (or [`mamba`](https://mamba.readthedocs.io/)):

```bash
conda install -c conda-forge pyrcs
```

</details>

For detailed options and development setup, see the full [Installation Guide](https://pyrcs.readthedocs.io/en/latest/installation.html).

## Quick start

For a concise guide on how to use PyRCS, check out the [Quick Start](https://pyrcs.readthedocs.io/en/latest/quick-start.html) tutorial, which includes illustrative examples for three frequently-used code categories in the UK railway system:

* [Location identifiers](http://www.railwaycodes.org.uk/crs/crs0.shtm) (CRS, NLC, TIPLOC and STANOX codes)
* [Engineer’s Line References](http://www.railwaycodes.org.uk/elrs/elr0.shtm) (ELRs) and their associated mileage files
* [Railway station data](http://www.railwaycodes.org.uk/stations/station1.shtm) (mileages, operators and grid coordinates)
* [Location identifiers](http://www.railwaycodes.org.uk/crs/crs0.shtm) (CRS, NLC, TIPLOC and STANOX codes)
* [Engineer’s Line References](http://www.railwaycodes.org.uk/elrs/elr0.shtm) (ELRs) and their associated mileage files
* [Railway station data](http://www.railwaycodes.org.uk/stations/station1.shtm) (mileages, operators and grid coordinates)

## Documentation

The complete PyRCS Documentation is available in [HTML](https://pyrcs.readthedocs.io/en/latest/) and [PDF](https://pyrcs.readthedocs.io/_/downloads/en/latest/pdf/) formats.
The complete PyRCS Documentation is available in [HTML](https://pyrcs.readthedocs.io/en/latest/) and [PDF](https://pyrcs.readthedocs.io/_/downloads/en/latest/pdf/) formats.

It is hosted on [Read the Docs](https://app.readthedocs.org/projects/pyrcs/), and the HTML version is also accessible via [GitHub Pages](https://mikeqfu.github.io/pyrcs/). The documentation includes detailed examples, tutorials and comprehensive references to help users get the most out of PyRCS.

## Cite as

Fu, Q. (2020). PyRCS: an open-source tool for collecting railway codes used in different UK rail industry systems. Zenodo. [doi:10.5281/zenodo.4026744](https://doi.org/10.5281/zenodo.4026744)
Fu, Q. (2020). PyRCS: an open-source tool for collecting railway codes used in different UK rail industry systems. Zenodo. [doi:10.5281/zenodo.4026744](https://doi.org/10.5281/zenodo.4026744)

```bibtex
@software{Fu_PyRCS_2020,
Expand All @@ -81,14 +108,14 @@ Fu, Q. (2020). PyRCS: an open-source tool for collecting railway codes used in d
}
```

For specific version references, please refer to [Zenodo](https://zenodo.org/search?q=conceptrecid%3A%224026744%22&f=allversions%3Atrue&l=list&p=1&s=10&sort=version).
For specific version references, please refer to [Zenodo](https://zenodo.org/search?q=conceptrecid%3A%224026744%22&f=allversions%3Atrue&l=list&p=1&s=10&sort=version).

## License

PyRCS is licensed under the [MIT License](https://github.com/mikeqfu/pyrcs/blob/master/LICENSE).
PyRCS is licensed under the [MIT License](https://github.com/mikeqfu/pyrcs/blob/master/LICENSE).

Please note that this project was initially licensed under the [GPLv3+](https://github.com/mikeqfu/pyrcs/blob/0.3.7/LICENSE) up to version *0.3.7*. Starting with version *1.0.0*, it has been re-licensed under the MIT License.
Please note that this project was initially licensed under the [GPLv3+](https://github.com/mikeqfu/pyrcs/blob/0.3.7/LICENSE) up to version *0.3.7*. Starting with version *1.0.0*, it has been re-licensed under the MIT License.

## Acknowledgement

PyRCS uses data available from the [Railway Codes](http://www.railwaycodes.org.uk/index.shtml) website. The time and effort that the website's editor and [all contributors](http://www.railwaycodes.org.uk/misc/acknowledgements.shtm) put in making the site and data available are fully credited.
PyRCS uses data available from the [Railway Codes](http://www.railwaycodes.org.uk/index.shtml) website. The time and effort that the website's editor and [all contributors](http://www.railwaycodes.org.uk/misc/acknowledgements.shtm) put in making the site and data available are fully credited.
13 changes: 8 additions & 5 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,17 @@ PyRCS

*An open-source tool for collecting railway codes used in different UK rail industry systems.*

|PyPI| |Python| |License| |Docs| |Build| |Codacy| |Codecov| |DOI|
|PyPI| |Conda-Forge| |Python| |License| |Docs| |Build| |Codacy| |Codecov| |DOI|

.. |PyPI| image:: https://img.shields.io/pypi/v/pyrcs
:alt: PyPI Release Version
.. |PyPI| image:: https://img.shields.io/pypi/v/pyrcs?logo=pypi
:alt: PyPI Version
:target: https://pypi.org/project/pyrcs/
.. |Python| image:: https://img.shields.io/pypi/pyversions/pyrcs
.. |Conda-Forge| image:: https://img.shields.io/conda/vn/conda-forge/pyrcs?logo=anaconda
:alt: Conda-Forge Version
:target: https://anaconda.org/channels/conda-forge/packages/pyrcs/overview
.. |Python| image:: https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fmikeqfu%2Fpyrcs%2Frefs%2Fheads%2Fmaster%2Fpyproject.toml
:alt: Python Version
:target: https://docs.python.org/3/
:target: https://www.python.org/downloads/
.. |License| image:: https://img.shields.io/github/license/mikeqfu/pyrcs
:alt: License
:target: https://github.com/mikeqfu/pyrcs/blob/master/LICENSE
Expand Down
70 changes: 63 additions & 7 deletions docs/source/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,24 @@
Installation
============

PyRCS can be installed using `uv`_ (recommended for speed, reliability and modern dependency resolution) or traditional `pip`_.
PyRCS can be installed via `uv`_ (recommended for speed, reliability and modern dependency resolution), `pixi`_, traditional `pip`_ or `conda-forge`_.


Using ``uv`` (Recommended)
==========================

`uv`_ is a fast Python package installer and project manager written in Rust.

Adding to a ``uv`` Project
---------------------------
Adding to a ``uv`` project
--------------------------

To add the latest release of PyRCS to your existing project managed by ``uv``:
To add the latest release of PyRCS to your existing project managed by `uv`_:

.. code-block:: console

> uv add pyrcs

Installing in a Virtual Environment
Installing in a virtual environment
-----------------------------------

If you are working inside an active virtual environment and wish to install PyRCS directly using ``uv pip``:
Expand All @@ -31,7 +32,37 @@ To install the latest development version directly from `GitHub <https://github.

.. code-block:: console

> uv pip install --upgrade git+https://github.com/mikeqfu/pyrcs.git
> uv pip install --upgrade git+[https://github.com/mikeqfu/pyrcs.git](https://github.com/mikeqfu/pyrcs.git)


Using ``pixi``
==============

`pixi`_ is a modern package management tool built on top of `conda-forge`_.

Adding to a ``pixi`` project
-----------------------------

To add the core PyRCS package to a workspace using `pixi`_:

.. code-block:: console

> pixi add pyrcs

Alternatively, to install PyRCS with PyPI extras inside a `pixi`_ project:

.. code-block:: console

> pixi add --pypi pyrcs

Installing globally
-------------------

To install PyRCS as a globally accessible tool via `pixi`_:

.. code-block:: console

> pixi global install pyrcs


Using ``pip``
Expand All @@ -55,6 +86,27 @@ To install the development version from GitHub:
- For general guidelines on Python virtual environments and dependency management, refer to the `Python Packaging User Guide`_.


Using ``conda`` or ``mamba``
============================

PyRCS is published on `conda-forge`_ and can be managed using `conda`_ or `mamba`_.

Installing the core package
---------------------------

To install PyRCS into an active environment using `conda`_:

.. code-block:: console

> conda install -c conda-forge pyrcs

Or, using `mamba`_:

.. code-block:: console

> mamba install -c conda-forge pyrcs


Verification
============

Expand All @@ -71,7 +123,11 @@ To verify the installation, import the package in a Python interpreter shell:


.. _`uv`: https://docs.astral.sh/uv/
.. _`pixi`: https://pixi.sh/
.. _`conda-forge`: https://anaconda.org/conda-forge/pyrcs
.. _`conda`: https://docs.conda.io/
.. _`mamba`: https://mamba.readthedocs.io/
.. _`virtual environment`: https://packaging.python.org/glossary/#term-Virtual-Environment
.. _`pip install`: https://pip.pypa.io/en/stable/cli/pip_install/
.. _`pip`: https://pip.pypa.io/en/stable/cli/pip/
.. _`Python Packaging User Guide`: https://packaging.python.org/tutorials/installing-packages/
.. _`Python Packaging User Guide`: https://packaging.python.org/tutorials/installing-packages/
Loading