xref: /petsc/lib/petsc/bin/maint/petsclinter/petsclinter/checks/_docs.py (revision 4c7cc9c8e01791debde927bc0816c9a347055c8f) 
1#!/usr/bin/env python3
2"""
3# Created: Mon Jun 20 18:53:35 2022 (-0400)
4# @author: Jacob Faibussowitsch
5"""
6from __future__ import annotations
7
8from .._typing import *
9
10from ..classes._diag import DiagnosticManager
11
12from ..classes.docs._doc_str     import PetscDocString, SectionManager
13from ..classes.docs._doc_section import (
14  DefaultSection, FunctionSynopsis, EnumSynopsis, FunctionParameterList, OptionDatabaseKeys, Level,
15  Notes, FortranNotes, DeveloperNotes, SourceCode, References, SeeAlso
16)
17
18def _do_docstring_check(DocStringType: type[PetscDocStringImpl], linter: Linter, cursor: Cursor) -> None:
19  r"""Do the actual docstring checking
20
21  Parameters
22  ----------
23  DocStringType :
24    the type of the docstring to instantiate
25  linter :
26    the linter instance
27  cursor :
28    the cursor instance to lint
29  """
30  docstring = DocStringType(linter, cursor)
31
32  with DiagnosticManager.push_from(docstring.get_pragmas()):
33    for section in docstring.parse().sections:
34      section.check(linter, cursor, docstring)
35  return
36
37class PetscFunctionDocString(PetscDocString):
38  sections = SectionManager(
39    FunctionSynopsis(),
40    FunctionParameterList(),
41    OptionDatabaseKeys(),
42    Notes(),
43    SourceCode(),
44    DeveloperNotes(),
45    References(),
46    FortranNotes(),
47    Level(),
48    SeeAlso(),
49    DefaultSection()
50  )
51
52"""Specific 'driver' function to test a particular docstring archetype"""
53def check_petsc_function_docstring(linter: Linter, cursor: Cursor) -> None:
54  r"""Check a PETSc function docstring
55
56  Parameters
57  ----------
58  linter :
59    the linter to check the docstring with
60  cursor :
61    the cursor representing the function declaration
62  """
63  return _do_docstring_check(PetscFunctionDocString, linter, cursor)
64
65class PetscEnumDocString(PetscDocString):
66  sections = SectionManager(
67    EnumSynopsis(),
68    OptionDatabaseKeys(),
69    Notes(),
70    SourceCode(),
71    DeveloperNotes(),
72    References(),
73    FortranNotes(),
74    Level(),
75    SeeAlso(),
76    DefaultSection()
77  )
78
79def check_petsc_enum_docstring(linter: Linter, cursor: Cursor) -> None:
80  r"""Check a PETSc enum docstring
81
82  Parameters
83  ----------
84  linter :
85    the linter to check the docstring with
86  cursor :
87    the cursor representing the enum declaration
88  """
89  return _do_docstring_check(PetscEnumDocString, linter, cursor)
90