algorand / algorand/pyteal

Add nitpick-mode in sphinx-docs

Aperta
#491 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Team Scytale
Lingua principale
Python
Stelle
288
Fork
138
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Descrizione

## 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.

```python

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?

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.