.gitlab-ci.yml

@@ -128,6 +128,7 @@ packaging-pip:
     - python setup.py sdist bdist_wheel
   artifacts:
     paths:
+      - .pypirc # required by job gitlab-pypi-package
       - dist/*
 
 documentation:
@@ -154,14 +155,21 @@ gitlab-pypi-package:
   image: python:3.9-slim-buster
   variables:
     GIT_STRATEGY: none
+    TWINE_PASSWORD: "${CI_JOB_TOKEN}"
+    TWINE_USERNAME: "gitlab-ci-token"
+    TWINE_REPOSITORY_URL: "https://gitlab.gpf-tech.ign.fr/api/v4/projects/${CI_PROJECT_ID}/packages/pypi"
   needs:
     - job: packaging-pip
       artifacts: true
   only:
     - tags
+  before_script:
+    - ls -lavh dist/
+    - python -m pip install --upgrade pip setuptools wheel
   script:
-    - python -m pip install twine
-    - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository gitlab-gpf dist/*
+    - python -m pip install -U "twine<5"
+    - python -m twine check dist/*
+    - python -m twine upload --verbose dist/*
 
 release_job:
   stage: 🚀 deploy

.pypirc

 [distutils]
 index-servers =
-    gitlab-gpf
+    gitlab-gpf-ci
+    gitlab-gpf-prj-dt
+    gitlab-gpf-pat
 
-[gitlab-gpf]
-repository = https://gitlab.gpf-tech.ign.fr/api/v4/groups/${env.CI_PROJECT_NAMESPACE}/packages/pypi
+; deploy using token generated in CI/CD
+[gitlab-gpf-ci]
+repository = https://gitlab.gpf-tech.ign.fr/api/v4/projects/${env.CI_PROJECT_ID}/packages/pypi
 username = gitlab-ci-token
 password = ${env.CI_JOB_TOKEN}
+
+; deploy for project using group deploy token
+; see: https://gitlab.gpf-tech.ign.fr/groups/geoplateforme/scripts-verification/-/settings/repository
+[gitlab-gpf-prj-dt]
+repository = https://gitlab.gpf-tech.ign.fr/api/v4/projects/176/packages/pypi
+username = <deploy token username>
+password = <deploy token>
+
+; deploy with Personal Access Token with scope api
+; see: https://gitlab.gpf-tech.ign.fr/-/profile/personal_access_tokens
+[gitlab-gpf-pat]
+repository = https://gitlab.gpf-tech.ign.fr/api/v4/projects/176/packages/pypi
+username = <your_personal_access_token_name>
+password = <your_personal_access_token>

CHANGELOG.md

@@ -16,6 +16,11 @@ Unreleased
 
 -->
 
+## 0.1.3 - 2022-11-16
+
+- Documentation: add how to publish and install
+- Fix: CD job was not using the .pypirc file
+
 ## 0.1.2 - 2022-11-16
 
 - Fix: repository URL was not updated in .pypirc

README.md

@@ -4,35 +4,8 @@
 
 [![coverage report](https://gitlab.gpf-tech.ign.fr/geoplateforme/scripts-verification/check-md5/badges/main/coverage.svg)](https://gitlab.gpf-tech.ign.fr/geoplateforme/scripts-verification/check-md5/-/commits/main)
 
-## Développement
-
-### Cloner le dépôt derrière le proxy
-
-L'Usine Logicielle étant en accès restreint derrière un filtre IP, les personnes ne disposant pas d'IP fixe passent par un proxy qui pointe sur un serveur de rebond dont l'IP fixe est autorisée.
-
-Exemple pour Oslandia avec l'utilisateur `geojulien` :
-
-```sh
-git clone --config http.proxy='socks5://127.0.0.1:8645' --config 'credential.helper=store' https://geojulien@gitlab.gpf-tech.ign.fr/geoplateforme/scripts-verification/check-md5.git
-```
-
-### Démarrage rapide
-
-Exemple sur une distribution Linux de type Ubuntu LTS :
-
-```sh
-# environnement virtuel
-python3 -m venv .venv
-# mise à jour de pip dans l'environnement virtuel
-python -m pip install -U pip
-# installation des dépendances de base
-python -m pip install -U -r requirements.txt
-# installation du projet en mode développement
-python -m pip install -e .
-```
-
 ----
 
 ## Contribuer
 
-Lire le guide de  [contribution](CONTRIBUTING.md) et la documentation.
+Lire le guide de [développement](https://geoplateforme.pages.gpf-tech.ign.fr/scripts-verification/check-md5/development/setup.html), les règles de [contribution](CONTRIBUTING.md) et la [documentation](https://geoplateforme.pages.gpf-tech.ign.fr/scripts-verification/check-md5/).

docs/development/publish.md

+# Publish
+
+## Publish package to GitLab Package Registry
+
+### Requirements
+
+- Python >= 3.9
+- Network access granted to:
+  - the GitLab instance
+  - <https://pypi.org>
+- a deploy token with `read_package_registry` and `write_package_registry` scope
+
+> See: [GitLab documentation about publishing to the package registry](https://docs.gitlab.com/ee/user/packages/pypi_repository/)
+
+### Configuration
+
+Fill the `.pypirc` file with the credentials.
+
+From here, we use the deploy token:
+
+```rc
+; deploy for project using group deploy token
+; see: https://gitlab.gpf-tech.ign.fr/groups/geoplateforme/scripts-verification/-/settings/repository
+[gitlab-gpf-prj-dt]
+repository = https://gitlab.gpf-tech.ign.fr/api/v4/projects/176/packages/pypi
+username =
+password =
+```
+
+### Build and upload with twine
+
+1. Install/upgrade twine:
+
+    ```sh
+    python3 -m pip install -U "twine<5"
+    ```
+
+1. Clean previous builds:
+
+    ```sh
+    rm -R dist/
+    ```
+
+1. Build the new version:
+
+    ```sh
+    python setup.py sdist bdist_wheel
+    ```
+
+1. Upload it to the package registry:
+
+    ```sh
+    twine upload --config-file .pypirc --repository gitlab-gpf-checks-dt --verbose dist/*
+    ```
+
+### Proxy support
+
+#### Socks5 proxy
+
+Install PySocks:
+
+```sh
+pip install -U "PySocks<2"
+```
+
+Example with a proxy on `127.0.0.1:8645`:
+
+```sh
+HTTPS_PROXY=socks5://127.0.0.1:8645 twine upload --config-file .pypirc --repository gitlab-gpf-checks-dt --verbose dist/*
+```
+
+> See: [Twine documentation](https://twine.readthedocs.io/en/stable/index.html#proxy-support)

docs/development/releasing.md

 # Release workflow
 
-1. Fill the `CHANGELOG.md`
+1. Fill the `CHANGELOG.md` with the new version
 1. Change the version number in `__about__.py`
 1. Apply a git tag with the relevant version: `git tag -a 0.3.0 {git commit hash} -m "New awesome feature"`
-1. Push tag to main branch: `git push origin 0.3.0`
+1. Push tag to main branch: `git push origin --tags`

docs/development/setup.md

+# Configurer l'environnement de développement
+
+## Prérequis système
+
+- Python >= 3.9
+- Accès réseau sur:
+  - l'instance GitLab : <https://gitlab.gpf-tech.ign.fr>
+  - le dépôt officiel de paquets Python : <https://pypi.org/>
+- un [jeton d'accès personnel ou Personal Access Token (PAT)](https://gitlab.gpf-tech.ign.fr/-/profile/personal_access_tokens) avec le scope `read_api`
+
+## Cloner le dépôt
+
+Exemple pour Oslandia avec l'utilisateur `geojulien` :
+
+```sh
+git clone --config 'credential.helper=store' https://geojulien@gitlab.gpf-tech.ign.fr/geoplateforme/scripts-verification/check-md5.git
+```
+
+### Derrière le proxy
+
+L'Usine Logicielle étant en accès restreint derrière un filtre IP, les personnes ne disposant pas d'IP fixe passent par un proxy qui pointe sur un serveur de rebond dont l'IP fixe est autorisée.
+
+Exemple avec un proxy de type socks :
+
+```sh
+git clone --config http.proxy='socks5://127.0.0.1:8645' --config 'credential.helper=store' https://geojulien@gitlab.gpf-tech.ign.fr/geoplateforme/scripts-verification/check-md5.git
+```
+
+## Démarrage rapide
+
+Exemple sur une distribution Linux de type Ubuntu LTS :
+
+```sh
+# environnement virtuel
+python3 -m venv .venv
+source .venv/bin/activate
+# mise à jour de pip dans l'environnement virtuel
+python -m pip install -U pip setuptools wheel
+# installation des dépendances de base
+python -m pip install -U -r requirements.txt
+# installation du projet en mode développement
+python -m pip install -e .
+```

docs/index.md

@@ -8,17 +8,27 @@
 
 ---
 
+```{toctree}
+---
+caption: Usage
+maxdepth: 1
+---
+installation
+```
+
 ```{toctree}
 ---
 caption: Development
 maxdepth: 1
 ---
-Code documentation <_apidoc/modules>
+development/setup
 development/contribute
 development/documentation
 development/testing
 development/releasing
+development/publish
 development/history
+Code documentation <_apidoc/modules>
 ```
 
 ```{toctree}

docs/installation.md

+# Installation
+
+Il est possible d'installer le projet de deux façon différentes, en plus de [celle du mode développement](development/setup).
+
+## Pip
+
+### Prérequis
+
+- Python >= 3.9
+- Accès réseau sur:
+  - l'instance GitLab : <https://gitlab.gpf-tech.ign.fr>
+  - le dépôt officiel de paquets Python : <https://pypi.org/>
+- un [jeton d'accès personnel ou Personal Access Token (PAT)](https://gitlab.gpf-tech.ign.fr/-/profile/personal_access_tokens) avec le scope `read_api`
+
+### Installer
+
+Dans les commandes suivantes, remplacer :
+
+- `<personal_access_token_name>` avec le nom de votre jeton (PAT). Exemple : `oche`
+- `<personal_access_token_value>` avec la valeur de votre jeton (PAT). Exemple : `aBcdEfghIJKLMNoP9R7s`
+
+```sh
+# Windows: py -3
+python3 -m pip install -U gpf-md5-checker --index-url https://<personal_access_token_name>:<your_personal_token>/api/v4/groups/55/-/packages/pypi/simple
+```
+
+#### Derrière un proxy
+
+Pour les proxy de type socks, installer :
+
+```sh
+python3 -m pip install -U "PySocks<2"
+```
+
+Puis ajouter l'URL du proxy en option :
+
+```sh
+# Windows: py -3
+python3 -m pip install -U gpf-md5-checker --index-url https://<personal_access_token_name>:<your_personal_token>/api/v4/groups/55/-/packages/pypi/simple --proxy socks5://localhost:8645
+```
+
+:::{note}
+Nous utilisons ici l'identifiant du groupe `geoplateforme` (`55`). Cet identifiant est visible sous le nom, sur [la page du groupe](https://gitlab.gpf-tech.ign.fr/geoplateforme).  
+Il est aussi possible d'utiliser le [registre lié au projet](https://gitlab.gpf-tech.ign.fr/geoplateforme/scripts-verification/check-md5/-/packages) où des instructions détaillées sont fournies au clic sur le package :
+
+![Détails d'un package sur le registre GitLab](/static/gitlab_package_registry_project_sample_details.png)
+:::
+
+----
+
+## Docker
+
+> Bientôt dans vos documentations

md5_checker/__about__.py

@@ -40,7 +40,7 @@ __uri_repository__ = (
 __uri_tracker__ = "https://gitlab.gpf-tech.ign.fr/geoplateforme/scripts-verification/check-md5/issues/"
 __uri__ = __uri_repository__
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 __version_info__ = tuple(
     [
         int(num) if num.isdigit() else num