From 0de3b5e2f93bf162f3c94b1b3eb18cf522962725 Mon Sep 17 00:00:00 2001 From: Heinz-Alexander Fuetterer <35225576+afuetterer@users.noreply.github.com> Date: Fri, 7 Jun 2024 15:50:51 +0200 Subject: [PATCH] docs: add installation guide (#129) Fixes #51 --- .github/templates/.release_notes.md.j2 | 2 +- README.md | 4 +- docs/mkdocs.yml | 3 + docs/src/install.md | 144 +++++++++++++++++++++++++ 4 files changed, 151 insertions(+), 2 deletions(-) create mode 100644 docs/src/install.md diff --git a/.github/templates/.release_notes.md.j2 b/.github/templates/.release_notes.md.j2 index 3736ef6..5cfedfa 100644 --- a/.github/templates/.release_notes.md.j2 +++ b/.github/templates/.release_notes.md.j2 @@ -12,7 +12,7 @@ You can install this version via pip from [PyPI](https://pypi.org/project/python python -m pip install python-re3data=={{ version }} ``` -or pull the Docker image from [ghcr.io](https://github.com/afuetterer/python-re3data/pkgs/container/python-re3data): +or pull the Docker image from [GHCR](https://github.com/afuetterer/python-re3data/pkgs/container/python-re3data): ```console docker pull ghcr.io/afuetterer/python-re3data:{{ version }} diff --git a/README.md b/README.md index 18c0795..2d3e3b2 100644 --- a/README.md +++ b/README.md @@ -68,12 +68,14 @@ You can install `python-re3data` via pip from [PyPI][pypi-url]: python -m pip install python-re3data ``` -or pull the Docker image from [ghcr.io](https://github.com/afuetterer/python-re3data/pkgs/container/python-re3data): +or pull the Docker image from [GHCR](https://github.com/afuetterer/python-re3data/pkgs/container/python-re3data): ```console docker pull ghcr.io/afuetterer/python-re3data:latest ``` +For a more detailed guide, see [Installation](https://afuetterer.github.io/python-re3data/latest/install/). + ## Documentation The [documentation][docs-url] is made with [Material for MkDocs](https://github.com/squidfunk/mkdocs-material) and is diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 3340c7f..e67a9e7 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -15,6 +15,8 @@ watch: nav: - Home: index.md +- Getting Started: + - Installation: install.md - Reference: - API Reference: api.md - Resources: resources.md @@ -65,6 +67,7 @@ plugins: markdown_extensions: - admonition +- footnotes - pymdownx.highlight: anchor_linenums: true line_spans: __span diff --git a/docs/src/install.md b/docs/src/install.md new file mode 100644 index 0000000..2092d54 --- /dev/null +++ b/docs/src/install.md @@ -0,0 +1,144 @@ +# Installation + +## Installing with pip (Recommended) + +To install using `pip`, run the following command: + +```bash +python -m pip install python-re3data +``` + +This will automatically install compatible versions of all dependencies, including `httpx` and `xsdata`. + +!!! note + It is highly recommended creating a virtual environment before installing the project. This will help keep your + dependencies isolated and prevent conflicts with other projects. You can use `venv` to create and manage virtual + environments. + +You can also install optional dependencies, such as the command line interface, by using `pip install python-re3data` +with the `[cli]` flag: + +```bash +python -m pip install "python-re3data[cli]" +``` + +For more details, see [Optional Dependencies](#optional-dependencies). + +### Requirements + +- Python 3.10 or higher installed on your machine + +!!! tip "Alternative: Use uv instead of pip" + [uv](https://github.com/astral-sh/uv)[^1] is a fast Python package installer and resolver, written in Rust. + + Create a virtual environment in the current directory: + + ```bash + uv venv + ``` + + Install the project and its dependencies: + + ```bash + uv pip install python-re3data + ``` + +## Pulling the Docker Image + +Pull the official image from [GHCR](https://github.com/afuetterer/python-re3data/pkgs/container/python-re3data): + +```bash +docker pull ghcr.io/afuetterer/python-re3data:latest +``` + +!!! note + The optional `[cli]` dependency group is pre-installed in the Docker image and the `re3data` executable is provided as + an entry point. + +Run the container with: + +```bash +$ docker run --rm afuetterer/python-re3data --version +0.5.0 +``` + +!!! tip "Alternative: Use Podman instead of Docker" + [Podman](https://podman.io/) is an open-source containerization platform that allows you to create, run, and manage + Linux containers. + + Pull the official image from [GHCR](https://github.com/afuetterer/python-re3data/pkgs/container/python-re3data): + + ```bash + podman pull ghcr.io/afuetterer/python-re3data:latest + ``` + + Run the container with: + + ```bash + $ podman run --rm afuetterer/python-re3data --version + 0.5.0 + ``` + +### Requirements + +- Docker[^2] or Podman[^3] installed and running on your machine + +## Installing from Source with Git + +Clone the repository from GitHub: + +```bash +git clone https://github.com/afuetterer/python-re3data.git +``` + +Change into the directory: + +```bash +cd python-re3data +``` + +Finally, install the project and its dependencies: + +```bash +python -m pip install . +``` + +### Requirements + +- Git installed on your machine +- Python 3.10 or higher installed on your machine + +## Dependencies + +### Required Dependencies + +`python-re3data` requires the following dependencies: + +| Package | Version | Description | +| ----------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- | +| [httpx](https://github.com/encode/httpx) | >= 0.27 | A modern and efficient HTTP client library, handles all API interactions. | +| [xsdata](https://github.com/tefra/xsdata) | >= 24.5 | A powerful tool for generating Python dataclasses from XML schemas, simplifies processing of API responses. | + +### Optional dependencies + +#### Command Line Interface + +Install with `python -m pip install "python-re3data[cli]"`. + +| Package | Version | Description | +| ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------- | +| [typer](https://github.com/tiangolo/typer) | >= 0.12 | a popular library for building command-line interfaces, powers the user-friendly interface. | + + + +[^1]: For installation instructions, see + [Getting Started](https://github.com/astral-sh/uv?tab=readme-ov-file#getting-started). + +[^2]: For installation instructions, see [Install Docker Engine](https://docs.docker.com/engine/install/). + +[^3]: For installation instructions, see [Podman Installation Instructions](https://podman.io/docs/installation).