Be able to override note on ansible-galaxy commands

[LvffY]

I'm currently building a private ansible collection. It contains roles and modules.

Because of this private aspect, it will (probably) never be uploaded to ansible-galaxy.

Now, when I'm build my documentation, I'd like the links and command in the note to fit my context. For example, just by running the normal antsibull commands, I have the following output :

But :

• the link behind itcorp_datalayer.deploy_app points to a link to https://galaxy.ansible.com which probably never exists.
• The command to install my collection isn't correct : in fact, I don't (and probably never) have an ansible-galaxy server. So this command ansible-galaxy collection install itcorp_datalayer.deploy_app will never work. So I'd like to be able to override the full command to reflect my git dependency setup.

Just for the record, I'm currently using a tox environment to build my docs and, before any changes I have the following builds :

[testenv:docs]
description = "Environment to generate docs"
skip_install = true
allowlist_externals =
    bash
    git
    cp
    mkdir
    rm
## This is needed to be able to use custom PYPI configuration
passenv =
    PIP_*
    HOME
    ANSIBLE_COLLECTIONS_PATH
deps =
    ansible
    antsibull
commands =
    mkdir -p {env:HOME}/tmp/docs
    antsibull-docs sphinx-init --use-current --dest-dir {env:HOME}/tmp/docs itcorp_datalayer.deploy_app
    pip install -r {env:HOME}/tmp/docs/requirements.txt
    bash -c '{env:HOME}/tmp/docs/build.sh'
    git rm -rf {toxinidir}/docs
    cp -rf {env:HOME}/tmp/docs/build/html {toxinidir}/docs
    rm -rf {env:HOME}/tmp/docs
    git add {toxinidir}/docs
    bash -c 'git diff-index --quiet HEAD || git commit -m "[TOOLS] 📝 Generate docs"'

So I think this could be great to be able to customize more the output of the documentations.

Workaround

As suggested by @felixfontein in the Ansible chat, I have updated the provided build.sh file to fit my needs. For now, I have the following tox setup

[testenv:docs]
description = "Environment to generate docs"
skip_install = true
allowlist_externals =
    bash
    git
    cp
    mkdir
    rm
## This is needed to be able to use custom PYPI configuration
passenv =
    PIP_*
    HOME
    ANSIBLE_COLLECTIONS_PATH
deps =
    ansible
    antsibull
commands =
    mkdir -p {env:HOME}/tmp/docs
    antsibull-docs sphinx-init --use-current --dest-dir {env:HOME}/tmp/docs itcorp_datalayer.deploy_app
    pip install -r {env:HOME}/tmp/docs/requirements.txt
    bash -c '{toxinidir}/build-docs.sh {env:HOME}/tmp/docs' # Here are the changes.
    git rm -rf {toxinidir}/docs
    cp -rf {env:HOME}/tmp/docs/build/html {toxinidir}/docs
    rm -rf {env:HOME}/tmp/docs
    git add {toxinidir}/docs
    bash -c 'git diff-index --quiet HEAD || git commit -m "[TOOLS] 📝 Generate docs"'

And my build-docs.sh looks like this :

#!/usr/bin/env bash
## This file is mostly extracted

set -e
cd ${1:?Please define the repository to find the ansible documentation}

# Create collection documentation into temporary directory
rm -rf temp-rst
mkdir -p temp-rst
antsibull-docs collection \
    --use-current \
    --no-use-html-blobs \
    --breadcrumbs \
    --indexes \
    --dest-dir temp-rst \
    itcorp_datalayer.deploy_app

# Copy collection documentation into source directory
rsync -cprv --delete-after temp-rst/collections/ rst/collections/

# Fix documentation to fit our needs
## Change ansible-galaxy URL to my Git URL
grep -rl 'https://galaxy.ansible.com/itcorp_datalayer/deploy_app' rst | xargs sed -i 's/galaxy.ansible.com\/itcorp_datalayer\/deploy_app/gitprovider.com\/path\/to\/my\/repository/g'
## Change ansible-galaxy command line to a git one
grep -rl 'ansible-galaxy collection install itcorp_datalayer.deploy_app' rst | xargs sed -i 's/ansible-galaxy collection install itcorp_datalayer.deploy_app/ansible-galaxy collection install git+https:\/\/gitprovider.com\/path\/to\/my\/repo,main/g'

# Build Sphinx site
sphinx-build -M html rst build -c . -W --keep-going

With this setup, I have the following output :

With the link pointing to what I want and the command looks like a command runnable in my context.

[felixfontein]

I'm wondering a bit how we should allow this to be configured.

1. Specifying this as CLI options is painful, especially for more complex configurations.
2. Making this configurable in antsibull.cfg seems a bit out of place, since that config file is more about 'global' antsibull settings than for settings for a specific docsite build.
3. Making this configurable per collection by some file in the collection artefact. This doesn't sound very flexible to me
4. One possibility would be creating a new config file (YAML based, what else) that can be specified for a docs build.

I'm currently tending to option 4.

[briantist]

First, I love this idea, especially as I'm ramping up private collection use at a company and expect to make heavy use of docs generation.

To me this sounds like a good fit for links.yml, but failing that a new file would be fine too.

[LvffY]

First, I love this idea, especially as I'm ramping up private collection use at a company and expect to make heavy use of docs generation.

To me this sounds like a good fit for links.yml, but failing that a new file would be fine too.

Also the file links.yml could fit for the URL link behind the name of the collection, I find that a bit weird to use it for the ansible-galaxy command

I think I'd prefer to use another file (but this is just an opinion :))

I'm wondering a bit how we should allow this to be configured.

1. Specifying this as CLI options is painful, especially for more complex configurations.
2. Making this configurable in antsibull.cfg seems a bit out of place, since that config file is more about 'global' antsibull settings than for settings for a specific docsite build.
3. Making this configurable per collection by some file in the collection artefact. This doesn't sound very flexible to me
4. One possibility would be creating a new config file (YAML based, what else) that can be specified for a docs build.

I'm currently tending to option 4.

@felixfontein Do you have any documentation about antsibull.cfg file ? Before knowing about this file, I think that the fourth option a better IMHO.

[felixfontein]

antsibull.cfg can look like this: https://github.com/ansible-community/antsibull-core/blob/main/antsibull.cfg

There are already some docs-specific configuration values in there (use_html_blobs, breadcrumbs, indexes), but it also has some settings that are usually more per user or per machine, like thread_max, process_max, collection_cache.

[felixfontein]

I've started some config file experiments in #26.