mirror of
https://github.com/ansible/ansible-documentation.git
synced 2026-03-27 13:28:51 +07:00
99 lines
3.6 KiB
Python
Executable File
99 lines
3.6 KiB
Python
Executable File
#!/usr/bin/env python
|
|
|
|
# To run this script, first make webdocs in the toplevel of the checkout.
|
|
# This will generate all rst files from their sources.
|
|
# Then run this script ./docs/bin/find-plugin-refs.py
|
|
#
|
|
# No output means that there are no longer any bare module and plugin names
|
|
# referenced via :ref:
|
|
#
|
|
# For my listing of what needs to be changed after running this script,
|
|
# see the comment at the end of the file
|
|
|
|
from __future__ import annotations
|
|
|
|
import glob
|
|
import os
|
|
import re
|
|
from collections.abc import Collection
|
|
|
|
TOPDIR = os.path.join(os.path.dirname(__file__), "..", "docsite", "rst")
|
|
|
|
|
|
def plugin_names(topdir: str | os.PathLike[str]):
|
|
plugins = set()
|
|
|
|
# Modules are in a separate directory
|
|
for module_filename in glob.glob(os.path.join(topdir, "modules", "*_module.rst")):
|
|
module_filename = os.path.basename(module_filename)
|
|
module_name = module_filename[: module_filename.index("_module.rst")]
|
|
plugins.add(module_name)
|
|
|
|
for plugin_filename in glob.glob(os.path.join(topdir, "plugins", "*", "*.rst")):
|
|
plugin_filename = os.path.basename(plugin_filename)
|
|
plugin_name = plugin_filename[: plugin_filename.index(".rst")]
|
|
plugins.add(plugin_name)
|
|
|
|
return plugins
|
|
|
|
|
|
def process_refs(topdir: str | os.PathLike[str], plugin_names: Collection[str]):
|
|
REF_RE = re.compile(":ref:`([^`]*)`")
|
|
LABEL_RE = re.compile("<([^>]*)>$")
|
|
|
|
# Walk the whole docs tree looking for :ref:.
|
|
# Anywhere those are found, search for `([^`]*)`
|
|
for dirpath, dirnames, filenames in os.walk(topdir):
|
|
for filename in filenames:
|
|
with open(os.path.join(dirpath, filename), "r") as f:
|
|
data = f.read()
|
|
for ref_match in re.finditer(REF_RE, data):
|
|
label = ref_match.group(1)
|
|
|
|
# If the ref label includes "<", then search for the label
|
|
# inside of the "<>"
|
|
label_match = re.search(LABEL_RE, label)
|
|
if label_match:
|
|
label = label_match.group(1)
|
|
|
|
# If the ref label is listed in plugins, then print that
|
|
# the file contains an unported ref
|
|
if label in plugin_names:
|
|
print(
|
|
":ref:`{0}` matching plugin {1} was found in {2}".format(
|
|
ref_match.group(1),
|
|
label,
|
|
os.path.join(dirpath, filename),
|
|
)
|
|
)
|
|
|
|
|
|
if __name__ == "__main__":
|
|
plugins = plugin_names(TOPDIR)
|
|
|
|
process_refs(TOPDIR, plugins)
|
|
|
|
# Fixes needed: docs/bin/plugin_formatter.py
|
|
# - t = _MODULE.sub(r":ref:`\1 <\1>`", t)
|
|
# + t = _MODULE.sub(r":ref:`\1 <module_\1>`", t)
|
|
#
|
|
# These have @{module}@ in the template and need to have something like
|
|
# module_@{module}@
|
|
# If any of these list plugins as well as modules,
|
|
# they will need to have a conditional or extra data passed in to handle
|
|
# that in a generic fashion:
|
|
#
|
|
# docs/templates/list_of_CATEGORY_modules.rst.j2
|
|
# docs/templates/list_of_CATEGORY_plugins.rst.j2
|
|
# docs/templates/modules_by_support.rst.j2
|
|
#
|
|
# These are just a simple manual fix:
|
|
# :ref:`command` matching plugin command was found in
|
|
# ./../docsite/rst/user_guide/intro_adhoc.rst
|
|
#
|
|
# :ref:`shell` matching plugin shell was found in
|
|
# ./../docsite/rst/user_guide/intro_adhoc.rst
|
|
#
|
|
# :ref:`config` matching plugin config was found in
|
|
# ./../docsite/rst/installation_guide/intro_configuration.rst
|