ansible-community/antsibull-docs

Docsite: See Also --> Lookup Module

samccann opened this issue · 7 comments

samccann commented

Summary

(issue manually moved over from ansible/ansible#79735) created by https://github.com/djarbz)

I am attempting to create my first collection.
Part of doing so is creating and verifying my documentation.

I would like to populate the seealso section, but it appears to be throwing an error.

Issue Type

Bug Report

Component Name

docs/docsite/rst/plugins/lookup.rst

Ansible Version

$ ansible --version
ansible [core 2.13.7]
  config file = /ansible/ansible.cfg
  configured module search path = ['/ansible/local/library']
  ansible python module location = /home/coder/.local/lib/python3.9/site-packages/ansible
  ansible collection location = /ansible/.galaxy:/ansible/local
  executable location = /home/coder/.local/bin/ansible
  python version = 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110]
  jinja version = 3.1.2
  libyaml = True

Configuration

# if using a version older than ansible-core 2.12 you should omit the '-t all'
$ ansible-config dump --only-changed -t all
CALLBACKS_ENABLED(/ansible/ansible.cfg) = ['ansible.posix.profile_tasks', 'ansible.posix.profile_roles']
COLLECTIONS_PATHS(/ansible/ansible.cfg) = ['/ansible/.galaxy', '/ansible/local']
DEFAULT_GATHERING(/ansible/ansible.cfg) = smart
DEFAULT_HOST_LIST(/ansible/ansible.cfg) = ['/ansible/inventory/hosts.yaml']
DEFAULT_LOOKUP_PLUGIN_PATH(/ansible/ansible.cfg) = ['/ansible/local/plugins/lookup']
DEFAULT_MODULE_PATH(/ansible/ansible.cfg) = ['/ansible/local/library']
DEFAULT_PRIVATE_KEY_FILE(/ansible/ansible.cfg) = /ansible/.ssh/id_ed25519
DEFAULT_REMOTE_USER(/ansible/ansible.cfg) = ansible
DEFAULT_ROLES_PATH(/ansible/ansible.cfg) = ['/ansible/.galaxy/roles', '/ansible/local']

CONNECTION:
==========

paramiko_ssh:
____________
remote_user(/ansible/ansible.cfg) = ansible

ssh:
___
private_key_file(/ansible/ansible.cfg) = /ansible/.ssh/id_ed25519
remote_user(/ansible/ansible.cfg) = ansible

OS / Environment

Debian 11 container on a Debian 11 host.
Container image is: docker.io/notmycloud/vsansible:v4-v6
Running on Podman.

Steps to Reproduce

See Also section of my documentation.

seealso:

# Reference by module name
- module: notmycloud.technitium_dns.login
  description: Lookup Module to authenticate with the T-DNS API.

Build Script

#!/usr/bin/env bash

set -e

generate_collection_rst () {
  ANSIBLE_COLLECTIONS_PATHS="${COLLECTION_ROOT}" antsibull-docs \
    collection \
    --use-current \
    --dest-dir temp-rst \
    "${1}"
}

ANSIBLE_ROOT="/ansible"
COLLECTION_ROOT="${ANSIBLE_ROOT}/local"
DOC_DIR="${ANSIBLE_ROOT}/docs"
mkdir -p "${DOC_DIR}"

# Initialize the Sphix Dir
antsibull-docs sphinx-init --use-current --dest-dir "${DOC_DIR}"
cd "${DOC_DIR}"
pip install --user -r requirements.txt

# Create collection documentation into temporary directory
rm -rf temp-rst
mkdir -p temp-rst
chmod og-w temp-rst  # antsibull-docs wants that directory only readable by itself

# Generate RST files for the following collections
generate_collection_rst notmycloud.technitium_dns

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

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

Expected Results

Antsibull compiles the documentation without an error message.
See also creates actual links.

Actual Results

Skipping /ansible/docs/.gitignore
Skipping /ansible/docs/antsibull-docs.cfg
Skipping /ansible/docs/build.sh
Skipping /ansible/docs/conf.py
Skipping /ansible/docs/requirements.txt
Skipping /ansible/docs/rst/index.rst
To build the docsite, go into /ansible/docs and run:
    pip install -r requirements.txt  # possibly use a venv
    ./build.sh
Requirement already satisfied: antsibull-docs<2.0.0,>=1.0.0 in /home/coder/.local/lib/python3.9/site-packages (from -r requirements.txt (line 5)) (1.9.0)
Requirement already satisfied: ansible-pygments in /home/coder/.local/lib/python3.9/site-packages (from -r requirements.txt (line 6)) (0.1.1)
Requirement already satisfied: sphinx in /home/coder/.local/lib/python3.9/site-packages (from -r requirements.txt (line 7)) (6.1.3)
Requirement already satisfied: sphinx-ansible-theme>=0.9.0 in /home/coder/.local/lib/python3.9/site-packages (from -r requirements.txt (line 8)) (0.9.1)
Requirement already satisfied: packaging in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (22.0)
Requirement already satisfied: asyncio-pool in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.6.0)
Requirement already satisfied: rstcheck<7.0.0,>=3.0.0 in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (6.1.1)
Requirement already satisfied: antsibull-core<3.0.0,>=1.2.0 in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.5.0)
Requirement already satisfied: jinja2 in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (3.1.2)
Requirement already satisfied: docutils in /home/coder/.local/lib/python3.9/site-packages (from antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.19)
Requirement already satisfied: pygments>=2.4.0 in /home/coder/.local/lib/python3.9/site-packages (from ansible-pygments->-r requirements.txt (line 6)) (2.13.0)
Requirement already satisfied: imagesize>=1.3 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.4.1)
Requirement already satisfied: requests>=2.25.0 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (2.28.1)
Requirement already satisfied: alabaster<0.8,>=0.7 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (0.7.12)
Requirement already satisfied: sphinxcontrib-serializinghtml>=1.1.5 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.1.5)
Requirement already satisfied: sphinxcontrib-qthelp in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.3)
Requirement already satisfied: importlib-metadata>=4.8 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (6.0.0)
Requirement already satisfied: babel>=2.9 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (2.11.0)
Requirement already satisfied: sphinxcontrib-jsmath in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.1)
Requirement already satisfied: sphinxcontrib-devhelp in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.2)
Requirement already satisfied: sphinxcontrib-applehelp in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (1.0.3)
Requirement already satisfied: sphinxcontrib-htmlhelp>=2.0.0 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (2.0.0)
Requirement already satisfied: snowballstemmer>=2.0 in /home/coder/.local/lib/python3.9/site-packages (from sphinx->-r requirements.txt (line 7)) (2.2.0)
Requirement already satisfied: sphinx-rtd-theme in /home/coder/.local/lib/python3.9/site-packages (from sphinx-ansible-theme>=0.9.0->-r requirements.txt (line 8)) (0.5.1)
Requirement already satisfied: twiggy>=0.5.0 in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.5.1)
Requirement already satisfied: aiohttp>=3.0.0 in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (3.8.3)
Requirement already satisfied: aiofiles in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (22.1.0)
Requirement already satisfied: perky in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.5.5)
Requirement already satisfied: sh in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.14.3)
Requirement already satisfied: pydantic in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.10.4)
Requirement already satisfied: PyYAML in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (6.0)
Requirement already satisfied: semantic_version in /home/coder/.local/lib/python3.9/site-packages (from antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (2.10.0)
Requirement already satisfied: pytz>=2015.7 in /home/coder/.local/lib/python3.9/site-packages (from babel>=2.9->sphinx->-r requirements.txt (line 7)) (2022.7)
Requirement already satisfied: zipp>=0.5 in /home/coder/.local/lib/python3.9/site-packages (from importlib-metadata>=4.8->sphinx->-r requirements.txt (line 7)) (3.11.0)
Requirement already satisfied: MarkupSafe>=2.0 in /home/coder/.local/lib/python3.9/site-packages (from jinja2->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (2.1.1)
Requirement already satisfied: urllib3<1.27,>=1.21.1 in /home/coder/.local/lib/python3.9/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (1.26.13)
Requirement already satisfied: idna<4,>=2.5 in /home/coder/.local/lib/python3.9/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (3.4)
Requirement already satisfied: certifi>=2017.4.17 in /home/coder/.local/lib/python3.9/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (2022.12.7)
Requirement already satisfied: charset-normalizer<3,>=2 in /home/coder/.local/lib/python3.9/site-packages (from requests>=2.25.0->sphinx->-r requirements.txt (line 7)) (2.1.1)
Requirement already satisfied: rstcheck-core<2.0.0,>=1.0.2 in /home/coder/.local/lib/python3.9/site-packages (from rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.0.3)
Requirement already satisfied: typer[all]<0.8,>=0.4.1 in /home/coder/.local/lib/python3.9/site-packages (from rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.7.0)
Requirement already satisfied: async-timeout<5.0,>=4.0.0a3 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (4.0.2)
Requirement already satisfied: yarl<2.0,>=1.0 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.8.2)
Requirement already satisfied: attrs>=17.3.0 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (22.1.0)
Requirement already satisfied: aiosignal>=1.1.2 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.3.1)
Requirement already satisfied: frozenlist>=1.1.1 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.3.3)
Requirement already satisfied: multidict<7.0,>=4.5 in /home/coder/.local/lib/python3.9/site-packages (from aiohttp>=3.0.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (6.0.4)
Requirement already satisfied: types-docutils<0.20,>=0.18 in /home/coder/.local/lib/python3.9/site-packages (from rstcheck-core<2.0.0,>=1.0.2->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.19.1.1)
Requirement already satisfied: typing-extensions>=4.2.0 in /home/coder/.local/lib/python3.9/site-packages (from pydantic->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (4.4.0)
Requirement already satisfied: six in /home/coder/.local/lib/python3.9/site-packages (from twiggy>=0.5.0->antsibull-core<3.0.0,>=1.2.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.16.0)
Requirement already satisfied: click<9.0.0,>=7.1.1 in /home/coder/.local/lib/python3.9/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (8.1.3)
Requirement already satisfied: shellingham<2.0.0,>=1.3.0 in /home/coder/.local/lib/python3.9/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (1.5.0.post1)
Requirement already satisfied: colorama<0.5.0,>=0.4.3 in /home/coder/.local/lib/python3.9/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.4.6)
Requirement already satisfied: rich<13.0.0,>=10.11.0 in /home/coder/.local/lib/python3.9/site-packages (from typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (12.6.0)
Requirement already satisfied: commonmark<0.10.0,>=0.9.0 in /home/coder/.local/lib/python3.9/site-packages (from rich<13.0.0,>=10.11.0->typer[all]<0.8,>=0.4.1->rstcheck<7.0.0,>=3.0.0->antsibull-docs<2.0.0,>=1.0.0->-r requirements.txt (line 5)) (0.9.1)
building file list ... done
environment_variables.rst
index_lookup.rst
notmycloud/technitium_dns/index.rst
notmycloud/technitium_dns/login_lookup.rst

sent 80,601 bytes  received 87 bytes  161,376.00 bytes/sec
total size is 80,611  speedup is 1.00
Running Sphinx v6.1.3
loading pickled environment... done
loading intersphinx inventory from ../python2.inv...
encountered some issues with some of the inventories, but they had working alternatives:
intersphinx inventory '../python2.inv' not fetchable due to <class 'FileNotFoundError'>: [Errno 2] No such file or directory: '/ansible/docs/rst/../python2.inv'
loading intersphinx inventory from ../python3.inv...
encountered some issues with some of the inventories, but they had working alternatives:
intersphinx inventory '../python3.inv' not fetchable due to <class 'FileNotFoundError'>: [Errno 2] No such file or directory: '/ansible/docs/rst/../python3.inv'
loading intersphinx inventory from ../jinja2.inv...
loading intersphinx inventory from ../ansible_devel.inv...
encountered some issues with some of the inventories, but they had working alternatives:
encountered some issues with some of the inventories, but they had working alternatives:
intersphinx inventory '../jinja2.inv' not fetchable due to <class 'FileNotFoundError'>: [Errno 2] No such file or directory: '/ansible/docs/rst/../jinja2.inv'
intersphinx inventory '../ansible_devel.inv' not fetchable due to <class 'FileNotFoundError'>: [Errno 2] No such file or directory: '/ansible/docs/rst/../ansible_devel.inv'
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 4 source files that are out of date
updating environment: 0 added, 4 changed, 0 removed
reading sources... [100%] collections/notmycloud/technitium_dns/login_lookup                                                                                                                                             
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                                                                           
/ansible/docs/rst/collections/notmycloud/technitium_dns/login_lookup.rst:436: WARNING: undefined label: 'ansible_collections.notmycloud.technitium_dns.login_module'
generating indices... done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 1 warning.

Code of Conduct

  • I agree to follow the Ansible Code of Conduct
felixfontein commented

To me the error message looks like there is a reference to a module that does not (yet) exist. So either removing that reference, or creating / documenting that module will fix this.

felixfontein commented

@djarbz does #96 (comment) apply to your collection?

djarbz commented

Hi @felixfontein, I haven't been able to get back at this for a while, but my interpretation is that because my seealso section has the - module key, it is looking for login_module.py instead of the login plugin.

felixfontein commented

@djarbz it is looking for an Ansible module called login in your collection, which should be located in plugins/modules/login.py.

djarbz commented

Ok, so how would I link to plugins/lookup/login.py?
I did not see an option for:

seealso:

# Reference by module name
- plugin: notmycloud.technitium_dns.login
  description: Lookup Module to authenticate with the T-DNS API.
felixfontein commented

That's because right now there is no option for it. It's part of the semantic markup specification (ansible-community/community-topics#53). Right now you have to use ref:

seealso:
  - ref: ansible_collections.notmycloud.technitium_dns.login_lookup
    description: Lookup plugin to authenticate with the T-DNS API.

I assume that with "lookup module" you mean "lookup plugin" (https://docs.ansible.com/ansible/latest/plugins/lookup.html).

djarbz commented

Yes, ok, I will use that for now then.

I think we can close this issue and I will follow that topic for future updates.

Thank you for your assistance.