Source code for galaxy.tool_util.linters.help

"""This module contains a linting function for a tool's help."""

from typing import (
    TYPE_CHECKING,
    Union,
)

from galaxy.tool_util.lint import Linter
from galaxy.util import (
    rst_to_html,
    unicodify,
)

if TYPE_CHECKING:
    from galaxy.tool_util.lint import LintContext
    from galaxy.tool_util.parser.interface import ToolSource


[docs]class HelpMissing(Linter):
[docs]    @classmethod
    def lint(cls, tool_source: "ToolSource", lint_ctx: "LintContext"):
        tool_xml = getattr(tool_source, "xml_tree", None)
        if not tool_xml:
            return
        root = tool_xml.find("./help")
        if root is None:
            root = tool_xml.getroot()
        help = tool_xml.find("./help")
        if help is None:
            lint_ctx.warn(
                "No help section found, consider adding a help section to your tool.", linter=cls.name(), node=root
            )


[docs]class HelpEmpty(Linter):
[docs]    @classmethod
    def lint(cls, tool_source: "ToolSource", lint_ctx: "LintContext"):
        tool_xml = getattr(tool_source, "xml_tree", None)
        if not tool_xml:
            return
        help = tool_xml.find("./help")
        if help is None:
            return
        help_text = help.text or ""
        if not help_text.strip():
            lint_ctx.warn("Help section appears to be empty.", linter=cls.name(), node=help)


[docs]class HelpPresent(Linter):
[docs]    @classmethod
    def lint(cls, tool_source: "ToolSource", lint_ctx: "LintContext"):
        tool_xml = getattr(tool_source, "xml_tree", None)
        if not tool_xml:
            return
        help = tool_xml.find("./help")
        if help is None:
            return
        help_text = help.text or ""
        if help_text.strip():
            lint_ctx.valid("Tool contains help section.", linter=cls.name(), node=help)


[docs]class HelpTODO(Linter):
[docs]    @classmethod
    def lint(cls, tool_source: "ToolSource", lint_ctx: "LintContext"):
        tool_xml = getattr(tool_source, "xml_tree", None)
        if not tool_xml:
            return
        help = tool_xml.find("./help")
        if help is None:
            return
        help_text = help.text or ""
        if "TODO" in help_text:
            lint_ctx.warn("Help contains TODO text.", linter=cls.name(), node=help)


[docs]class HelpInvalidRST(Linter):
[docs]    @classmethod
    def lint(cls, tool_source: "ToolSource", lint_ctx: "LintContext"):
        tool_xml = getattr(tool_source, "xml_tree", None)
        if not tool_xml:
            return
        help = tool_xml.find("./help")
        if help is None:
            return
        help_text = help.text or ""
        if not help_text.strip():
            return
        invalid_rst = rst_invalid(help_text)
        if invalid_rst:
            lint_ctx.warn(f"Invalid reStructuredText found in help - [{invalid_rst}].", linter=cls.name(), node=help)


[docs]class HelpValidRST(Linter):
[docs]    @classmethod
    def lint(cls, tool_source: "ToolSource", lint_ctx: "LintContext"):
        tool_xml = getattr(tool_source, "xml_tree", None)
        if not tool_xml:
            return
        help = tool_xml.find("./help")
        if help is None:
            return
        help_text = help.text or ""
        if not help_text.strip():
            return
        invalid_rst = rst_invalid(help_text)
        if not invalid_rst:
            lint_ctx.valid("Help contains valid reStructuredText.", linter=cls.name(), node=help)


[docs]def rst_invalid(text: str) -> Union[bool, str]:
    """
    Predicate to determine if text is invalid reStructuredText.
    Return False if the supplied text is valid reStructuredText or
    a string indicating the problem.
    """
    invalid_rst: Union[bool, str] = False
    try:
        rst_to_html(text, error=True)
    except Exception as e:
        invalid_rst = unicodify(e)
    return invalid_rst