Add nitpick-mode in sphinx-docs

[ahangsu]

Problem

Previously when we are handling issue #327 in PR #478, we attempted to use nitpicky mode in SPHINX_OPT (inside Makefile), but due to sphinx requiring all classes need to be exported, and at this moment (2022/08/03) we cannot find a way to specify a class to be unexported, we decided to open this ticket to remind us to allow -n to be activated at some point.

Solution

We used to add nitpick-ignore (regex) in docs/conf.py to ignore the warning, for warning would error by -W error on warning settings. The following is the nitpick configuration code snippet, hopefully it would be somewhat useful when we pick up the issue again.

class NitpickIgnore:
    @staticmethod
    def optional() -> list[tuple[str, str]]:
        """
        Ignores parameter declarations that specify _optional_ usage.
        """
        return [
            ("py:class", "optional"),
        ]

    @staticmethod
    def standard_library() -> list[tuple[str, str]]:
        """
        Ignores Python standard library references that Sphinx does not track.
        """
        return [
            ("py:class", "abc.ABC"),
        ]

    @staticmethod
    def unexported() -> list[tuple[str, str]]:
        """
        Ignores Pyteal internal unexported classes that Sphinx cannot track reference.
        """
        return [
            ("py:class", "pyteal.BlockField"),
            ("py:class", "pyteal.Base64Encoding"),
            ("py:class", "pyteal.VrfVerifyStandard"),
            ("py:class", "pyteal.JsonRefType"),
            ("py:class", "pyteal.OutputKwArgInfo"),
        ]


class NitpickIgnoreRegex:
    @staticmethod
    def type_vars() -> list[tuple[str, str]]:
        """
        Regex ignores generic TypeVar definitions that Sphinx does not track.
        """
        return [
            ("py.obj", r".*\.T$"),
            ("py.obj", r".*\.T[0-9]+$"),
            ("py.class", r".*\.T_co$"),
            ("py.obj", r".*\.T_co$"),
            ("py.class", r".*\.T$"),
            ("py.class", r"^T$"),
            ("py.obj", r".*\.N$"),
            ("py.class", r".*\.N$"),
            ("py.class", r"^N$"),
        ]

    @staticmethod
    def standard_library() -> list[tuple[str, str]]:
        """
        Regex ignores Python standard library references that Sphinx does not track.
        """
        return [
            ("py:class", r"contextlib\..*"),
            ("py:class", r"enum\..*"),
        ]

    @staticmethod
    def third_party() -> list[tuple[str, str]]:
        """
        Regex ignores 3rd party references that Sphinx does not track.
        """
        return [
            ("py:class", r"algosdk\.abi\..*"),
        ]


nitpick_ignore = (
    NitpickIgnore.optional()
    + NitpickIgnore.standard_library()
    + NitpickIgnore.unexported()
)

nitpick_ignore_regex = (
    NitpickIgnoreRegex.standard_library()
    + NitpickIgnoreRegex.third_party()
    + NitpickIgnoreRegex.type_vars()
)

Dependencies

Higher sphinx version that allows one to specify a way to hide a class from exporting.

Urgency

Not quite?