Metadata-Version: 2.4
Name: openmairie.devtools
Version: 1.4.2
Summary: openMairie Developer Tools
Author-email: openMairie <contact@openmairie.org>
License-Expression: GPL-2.0-or-later
Project-URL: Homepage, http://www.openmairie.org/framework
Project-URL: Source, https://gitlab.com/openmairie/openmairie.devtools/
Keywords: openMairie
Platform: any
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
Requires-Dist: setuptools
Requires-Dist: jinja2
Requires-Dist: unidecode
Requires-Dist: requests
Requires-Dist: reportlab
Requires-Dist: markdown
Requires-Dist: beautifulsoup4
Requires-Dist: argcomplete<=3.7.0

openmairie.devtools
===================

openMairie Developer Tools

.. image:: https://img.shields.io/pypi/v/openmairie.devtools.svg
    :target: https://pypi.python.org/pypi/openmairie.devtools/
    :alt: Latest PyPI version

.. contents::

Introduction
------------

openmairie.devtools is a collection of command-line programs and CI/CD configurations
to handle tasks on `openMairie Framework <http://www.openmairie.org/framework/>`_ based projects.
Mainly initialize environment, run tests, release a project, ...


Installation
------------

Command line tools : you just need `pip <https://pip.pypa.io>`_ ≥ 21.3 

.. code-block:: bash

    pip install openmairie.devtools

You can enable auto-completion for all the ``om-*`` commands at once using
`argcomplete <https://pypi.org/project/argcomplete/>`_'s global completion
hook. This is a one-time, per-machine setup,  so once it's done any other 
argcomplete-enabled tool will complete automatically too

.. code-block:: bash

    activate-global-python-argcomplete --user

If you'd rather not activate completion globally, you can register a
single command instead

.. code-block:: bash

    # For bash, with an on-demand completion
    mkdir -p ~/.local/share/bash-completion/completions/
    register-python-argcomplete --shell bash om-tests > ~/.local/share/bash-completion/completions/om-tests

    # For other shells, add this line to your shell's startup file
    # (.zshrc, ~/.config/fish/config.fish, ...)
    eval "$(register-python-argcomplete --shell <your-shell> om-tests)"


CI/CD components for GitLab
###########################

See documentation for each component in the `templates/` folder.

om-logo specifics
#################

For PNG rendering, Inkskape should be available. 
On Debian-based OS (Ubuntu, etc)

.. code-block:: bash

    sudo apt-get install inkscape

For other OS, please visit ::

    https://inkscape.org/en/release

You should have the right font (**Caviar Dream**) available on your system.
Get it there ::

    https://www.fontsquirrel.com/fonts/download/Caviar-Dreams


Available commands
------------------

om-tests
########

Should be run from the *tests* folder of your project and allow you to
initialize your test environment, to run all tests suites or to run only one
tests suite.

om-svnexternals
################

Install SVN dependencies listed in `EXTERNALS.txt`.

Should be run from the root of your project.  It scans for ``EXTERNALS.txt``
files and resolves each entry using the following strategy:

1. **GitLab package registry** — the SVN URL is parsed to derive a package
   name and version.  If a matching archive exists in the
   `openmairie/framework-openmairie <https://gitlab.com/openmairie/framework-openmairie/-/packages>`_
   generic package registry, it is downloaded and extracted.
2. **SVN export** — if no archive is found, a classic
   ``svn export --force --ignore-externals`` is performed and any nested
   ``EXTERNALS.txt`` discovered inside the export is resolved recursively.

Two URL patterns are recognised:

- **Externals** (``externals--`` prefixed packages)::

    .../externals/fpdf/tags/1.8.5/             → externals--fpdf          1.8.5
    .../externals/pear/pear-core/tags/v1.10.12 → externals--pear--pear-core v1.10.12
    .../externals/om-theme/kied/tags/2.0.0     → externals--om-theme--kied 2.0.0

- **Framework** (``openmairie_exemple``) — maps to the single package
  ``externals--framework-openmairie``.  The bundled archive (with resolved
  sub-externals) is preferred over the bare one::

    .../openmairie_exemple/tags/4.11.0-a16/core → core-bundle.tar.gz then core.tar.gz
    .../openmairie_exemple/tags/4.11.0-a16/lib  → lib-bundle.tar.gz  then lib.tar.gz

**Local cache**

Downloaded archives are cached locally so subsequent runs are near-instant.
The cache directory follows the
`XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/latest/>`_::

    $XDG_CACHE_HOME/om-devtools/packages/
    # or, when XDG_CACHE_HOME is not set:
    ~/.cache/om-devtools/packages/

**Options**

``-N``, ``--no-cache``
    Bypass the local cache and force re-download from the registry.  The
    downloaded archives are still stored in the cache for future use.

**Usage** ::

    cd /path/to/your/project
    om-svnexternals            # normal run (uses cache)
    om-svnexternals -N         # force re-download

om-release
##########

Performs the complete release cycle for openMairie PHP applications, 
replacing the legacy ``om.releaser`` package.
Should be run from the root of your project.  

The workflow has three phases:

1. **Prerelease** — version bump in ``VERSION.txt`` (or
   ``dyn/version.inc.php``), history file update, documentation link update,
   framework externals pinning, DB init & SQL file handling, commit.
2. **Release** — git tag.
3. **Postrelease** — bump to next development version (``.dev0``), new history
   section, framework externals unpinning, new SQL files, commit.

By default all three phases run in sequence.  Each phase can also be run
independently.

**Options**

``--prerelease``
    Run the prerelease phase only.

``--release``
    Run the release (tag) phase only.

``--postrelease``
    Run the postrelease phase only.

``--no-input``
    Don't ask questions, use default values (useful in CI).

``-v``, ``--verbose``
    Verbose mode (debug logging).

**Usage** ::

    cd /path/to/your/project
    om-release                  # full release (prerelease + tag + postrelease)
    om-release --prerelease     # prerelease only
    om-release --release        # tag only
    om-release --postrelease    # postrelease only

om-logo
#######

This command allows you to generate SVG and PNG logo for your openMairie
application, according to design's guideline available here ::

    http://www.openmairie.org/communaute/ressources-graphiques/openmairie-identite-visuelle.pdf

Full documentation is available from the help command ::

    om-logo --help


om-release-notes
################

Generates a release notes PDF (and CSV) from a GitLab milestone.  It fetches
all issues attached to the milestone, converts their markdown descriptions
(including images) to PDF, and produces a document with a cover page, table
of contents, and one section per issue category (evolutions, bugs, others).

**Usage** ::

    om-release-notes --project openmairie/openXXX --milestone "1.15.0"
    om-release-notes --project openmairie/openXXX --milestone "1.15.0" \
        --logo logo.png --output notes.pdf

Full documentation is available from the help command ::

    om-release-notes --help


Configuration
-------------

Global configuration is read from ``${XDG_CONFIG_HOME:-~/.config}/om-devtools/config.cfg``.

Example ``config.cfg``

.. code-block:: ini

    [browser]
    src_path = /path/to/browser/source
    dest_path = /path/to/browser/destination

    [gitlab]
    url = https://gitlab.com
    token = glpat-xxxxxxxxxxxxxxxxxxxx

Some commands interact with GitLab and need a GitLab private token. 
It can be provided by (read in this order): 

1. the ``--token`` command-line option
2. the ``GITLAB_TOKEN`` environment variable
3. the ``[gitlab]`` section of the configuration file

The GitLab URL defaults to ``https://gitlab.com`` and can be overridden with
``--gitlab-url``, the ``GITLAB_URL`` environment variable, or the ``[gitlab]``
section of the configuration file.

Changelog
=========

1.4.2 (2026-08-05)
------------------

- insure argcomplete is compatible python 3.9
  [epritchard2]


1.4.1 (2026-07-24)
------------------

- Fix argument autocompletion breaking the whole scripts
  [nathanaelhoun]
- Modernize python packaging by following PEP 621
  [nathanaelhoun]


1.4.0 (2026-07-24)
------------------

- Code base modernization.
  [nathanaelhoun]
- Always drop existing database on `ìnitenv`.
  [nathanaelhoun]
- GitLab CI/CD : new `build-robotframework-documentation` CI/CD component
  to build the robotframework documentation for all keywords of a given project
  and allow them to be published on GitLab Pages
  [nathanaelhoun]
- feat(om-release): add release workflow command replacing om.releaser.
  [flohcim, nathanaelhoun]
- feat(om-release-notes): new script to generate a PDF and CSV with release notes
  from a GitLab milestone. 
  [flohcim, nathanaelhoun]
- Rename configuration directory from ``~/.om-devtools/`` to `$XDG_CONFIG_HOME/om-devtools/`.
  The legacy paths are still read with a deprecation warning.
  [nathanaelhoun]


1.3.0 (2026-03-30)
------------------

- om-tests: ``runall`` command now excludes the ``dev`` tag by default.
  [epontagnier]
- om-svnexternals: resolve externals from GitLab generic package registry
  instead of svn export when the archive is available.  Falls back to
  svn export when not found.
  [flohcim]
- om-svnexternals: add local cache for downloaded archives
  (``~/.cache/om-devtools/packages/``).  Use ``-N`` / ``--no-cache``
  to force re-download.
  [flohcim]
- om-svnexternals: use ``svn export --force --ignore-externals`` and
  recursively resolve nested ``EXTERNALS.txt`` files.
  [flohcim]
- om-svnexternals: support framework URLs (``openmairie_exemple``) mapped to
  ``externals--framework-openmairie`` package with bundle priority.
  [flohcim]
- Rename configuration directory from ``~/.om-tests/`` to
  ``~/.om-devtools/``.  The legacy path is still read with a
  deprecation warning.
  [flohcim]


1.2.0 (2025-05-28)
------------------

- Fixed documentation for pabot.
  [rasseum]
- Added two contributors.
  [rasseum]
- Note: Version 1.1.1 should have been named 1.2.0. This 1.2.0 version restores
  proper versioning by correcting several aspects.
  [rasseum]

1.1.1 (2025-04-24)
------------------

- Add pabot to openmairie.devtools.
  [rasseum]


1.1.0 (2023-10-08)
------------------

- Use robot and not pybot command anymore.
  [flohcim]


1.0.0 (2022-05-10)
------------------

- Python 3 support only.
  [flohcim, tiazma]


0.4.0 (2018-04-10)
------------------

- Add 'additional_sql' option config to om-tests.
  [flohcim]


0.3.1 (2018-01-10)
------------------

- Removed unnecessary jinja2 env options
  [tiazma]


0.3.0 (2018-01-10)
------------------

- Added om-logo, application logo generation
  [tiazma]


0.2.2 (2017-11-25)
------------------

- Remove the externals was breaking travis CI.
  [flohcim]

0.2.1 (2017-11-24)
------------------

- Filename of EXTERNALS.txt file parsed was missing.
  [flohcim]

0.2.0 (2017-11-24)
------------------

- Add om-svnexternals script.
  [flohcim]


0.1 (2017-11-23)
----------------

- Initial release as a python package.
  [flohcim, fmichon, jymadier, mbroquet, nhaye, NHaye, nmeucci, oc1n, softime,
  stimezouaght, tiazma]

Contributors
============

* Étienne Pontagnier <epontagnier@atreal.fr> [epontagnier]
* Florent Michon <flohcim@gmail.com> [flohcim][fmichon]
* Grégory Malvolti <gmalvolti@atreal.fr> [gmalvolti]
* Jean-Yves Madier de Champvermeil <> [jymadier]
* Matthias Broquet <mbroquet@atreal.fr> [mbroquet][tiazma]
* Nathanaël Houn <nhoun@atreal.fr> [nathanaelhoun]
* Nicolas Haye <> [nhaye][NHaye]
* Nicolas Meucci <> [nmeucci][oc1n]
* Sofien Timezouaght <> [softime][stimezouaght]
* Rabah Asseum <rasseum@atreal.fr> [rasseum]
* Sébastien Dethyre <> [sdethyre]
