Skip to content

mkdocs_demo

mkdocs_demo module

config

config module

config

This module contains MkDocstrings configuration objects.

RefGenConfig dataclass

Dataclass to store MkDocstrings configuration.

handler class-attribute instance-attribute 
handler: Language = PYTHON

Handler language.

out_dir class-attribute instance-attribute 
out_dir: Path = Path('reference')

Output directory.

interfaces

This module contains interfaces and custom types.

ITrolling 

ITrolling(x: float, n: int)

Abstract base class for implementing trolling interface.

Parameters

x : float The parameter x is a float, which means it can hold decimal values. It is used to store a numerical value.

n : int The parameter n is an integer that represents the number of iterations or steps in a process.

Source code in src/mkdocs_demo/config/interfaces.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def __init__(self, x: float, n: int) -> None:
    """
    The above function is an initializer method for a class that takes in
    two parameters, `x` and `n`, and does not return anything.

    Parameters
    ----------
    `x` : `float`
        The parameter `x` is a float, which means it can hold decimal
        values. It is used to store a numerical value.

    `n` : `int`
        The parameter `n` is an integer that represents the number of
        iterations or steps in a process.
    """

    self.x = x
    self.n = n
n instance-attribute 
n = n
x instance-attribute 
x = x
__repr__ 
__repr__() -> str
Source code in src/mkdocs_demo/config/interfaces.py 
51
52
def __repr__(self) -> str:
    return f"""{self.x} * {self.n} = {self.multiple}"""
__str__ 
__str__() -> str
Source code in src/mkdocs_demo/config/interfaces.py 
48
49
def __str__(self) -> str:
    return f"""x={self.x}, n={self.n}, hence the multiple={self.multiple}"""
from_dict abstractmethod 
from_dict(d: dict[str, int]) -> Self
Source code in src/mkdocs_demo/config/interfaces.py 
59
60
61
@abstractmethod
def from_dict(cls, d: dict[str, int]) -> Self:
    pass
multiple abstractmethod 
multiple() -> float
Source code in src/mkdocs_demo/config/interfaces.py 
54
55
56
57
@abstractproperty
@abstractmethod
def multiple(self) -> float:
    pass

Language

Bases: Enum

Enum that represents different programming languages.

BASH class-attribute instance-attribute 
BASH: str = '*.sh'

Bash language.

PYTHON class-attribute instance-attribute 
PYTHON: str = '*.py'

Python language.

trivial

This module contains extreme triviality.

trivial_function 

trivial_function() -> Literal['OMG, thanks!']

Thanks for that.

Returns

Literal Absolutely useless string literal.

Source code in src/mkdocs_demo/config/trivial.py 
 7
 8
 9
10
11
12
13
14
15
16
17
def trivial_function() -> Literal["OMG, thanks!"]:
    """
    Thanks for that.

    Returns
    -------
    `Literal`
        Absolutely useless string literal.
    """

    return "OMG, thanks!"

lib

lib module.

factory

This module contains factory functions.

command_factory 

command_factory(cmd: str) -> Callable[..., int | None]

The factory function takes a command as input and returns a function that, when called, executes the command and returns the exit code or None if the execution is interrupted.

Parameters

cmd : str The cmd parameter is a string that represents a command to be executed.

Returns

Callable[..., int | None] The factory function returns a callable object, which is a function. The function takes no arguments and returns either an integer or None.

Source code in src/mkdocs_demo/lib/factory.py 
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
def command_factory(cmd: str) -> Callable[..., int | None]:
    """
    The `factory` function takes a command as input and returns a function that, when called, executes
    the command and returns the exit code or None if the execution is interrupted.

    Parameters
    ----------
    `cmd` : `str`
        The `cmd` parameter is a string that represents a command to be executed.

    Returns
    -------
    `Callable`[`...`, `int` | `None`]
        The factory function returns a callable object, which is a function. The function takes no
        arguments and returns either an integer or None.
    """

    def _func(_cmd: str = cmd) -> int | None:
        try:
            return subprocess.call(_cmd.split(" "), shell=False)
        except KeyboardInterrupt:
            pass

        return None

    return _func

mkdocstrings

This module contains code for auto-generating the codebase documentation.

gen_ref_pages 

gen_ref_pages(config: type[RefGenConfig]) -> Literal[True]

The gen_ref_pages function generates reference pages for Python modules and creates a navigation structure for them.

Parameters

config : type[RefGenConfig] The config parameter is of type RefGenConfig. It is used to provide configuration settings for generating reference pages.

Source code in src/mkdocs_demo/lib/mkdocstrings.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def gen_ref_pages(config: type[RefGenConfig]) -> Literal[True]:
    """
    The `gen_ref_pages` function generates reference pages for Python modules
    and creates a navigation structure for them.

    Parameters
    ----------
    `config` : `type`[`RefGenConfig`]
        The `config` parameter is of type `RefGenConfig`. It is used to provide configuration settings for
        generating reference pages.
    """

    nav = mkdocs_gen_files.Nav()
    src = Path(__file__).parent.parent.parent

    # Get paths for the give language handler
    for path in sorted(src.rglob(config.handler.value)):
        module_path = path.relative_to(src).with_suffix("")
        doc_path = path.relative_to(src).with_suffix(".md")
        full_doc_path = config.out_dir.joinpath(doc_path)

        parts = tuple(module_path.parts)

        match parts[-1]:
            case "__init__":
                parts = parts[:-1]
                doc_path = doc_path.with_name("index.md")
                full_doc_path = full_doc_path.with_name("index.md")
            case "__main__":
                continue

        nav[parts] = doc_path.as_posix()

        with mkdocs_gen_files.open(full_doc_path, "w") as fd:
            identifier = ".".join(parts)
            fd.write(f"::: {identifier}")

        mkdocs_gen_files.set_edit_path(full_doc_path, path)

    with mkdocs_gen_files.open(config.out_dir.joinpath("SUMMARY.md"), "w") as nav_file:
        nav_file.writelines(nav.build_literate_nav())

    return True

superfluous

This module contains additional trivial filler code.

TestClass 

TestClass(num_features: int, hidden_layers: int)

Bases: object

The TestClass is a basic Python class.

Parameters

num_features : int The num_features parameter represents the number of input features in your model. It indicates the size of the input layer of your neural network.

hidden_layers : int The hidden_layers parameter represents the number of hidden layers in a neural network.

Source code in src/mkdocs_demo/lib/superfluous.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def __init__(self, num_features: int, hidden_layers: int) -> None:
    """
    Initializes the number of features and the number of hidden layers for a neural network.

    Parameters
    ----------
    `num_features` : `int`
        The `num_features` parameter represents the number of input features in your model. It
        indicates the size of the input layer of your neural network.

    `hidden_layers` : `int`
        The `hidden_layers` parameter represents the number of hidden layers in a neural network.
    """

    self.num_features: int = num_features
    self.hidden_layers: int = hidden_layers
MODEL_TYPE class-attribute instance-attribute 
MODEL_TYPE: str = 'MLP'
hidden_layers instance-attribute 
hidden_layers: int = hidden_layers
num_features instance-attribute 
num_features: int = num_features
get_type staticmethod 
get_type() -> Literal['Neural Network']

The method get_type returns the string "Neural Network".

Returns

Literal The string "Neural Network".

Source code in src/mkdocs_demo/lib/superfluous.py 
130
131
132
133
134
135
136
137
138
139
140
141
@staticmethod
def get_type() -> Literal["Neural Network"]:
    """
    The method `get_type` returns the string "Neural Network".

    Returns
    -------
    `Literal`
        The string "Neural Network".
    """

    return "Neural Network"
load_model classmethod 
load_model(path: Path | str) -> str

The method load_model loads a model from a given path and returns a string indicating the path from which the model was loaded.

Parameters

path : Path | str The path parameter is the path to the model file that needs to be loaded. It can be either a string or a Path object.

Returns

str A string that indicates the path from which the model was loaded.

Source code in src/mkdocs_demo/lib/superfluous.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
@classmethod
def load_model(cls, path: Path | str) -> str:
    """
    The method `load_model` loads a model from a given path and returns a string indicating the
    path from which the model was loaded.

    Parameters
    ----------
    `path` : `Path` | `str`
        The `path` parameter is the path to the model file that needs to be loaded. It can be either a
        string or a `Path` object.

    Returns
    -------
    `str`
        A string that indicates the path from which the model was loaded.
    """

    if isinstance(path, str):
        path = Path(path)

    return f"Model loaded from: '{path}' - Type: {cls.MODEL_TYPE}"
show_model 
show_model() -> dict[str, str | int]

The method show_model returns a dictionary containing the model type and information about its layers.

Returns

dict[str, str | int] A dictionary containing the model type and the layers of the model.

Source code in src/mkdocs_demo/lib/superfluous.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def show_model(self) -> dict[str, str | int]:
    """
    The method `show_model` returns a dictionary containing the model type and information about
    its layers.

    Returns
    -------
    `dict`[`str`, `str` | `int`]
        A dictionary containing the model type and the layers of the model.
    """

    model_dict: dict[str, str | int] = {"model_type": self.MODEL_TYPE}
    model_dict.update(self._show_layers())

    return model_dict

Trolling 

Trolling(x: float, n: int)

Bases: ITrolling

The class Trolling implements the ITrolling interface.

Parameters

x : float The parameter x is a float, which means it can hold decimal values. It is used to store a numerical value.

n : int The parameter n is an integer that represents the number of iterations or steps in a process.

Source code in src/mkdocs_demo/config/interfaces.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def __init__(self, x: float, n: int) -> None:
    """
    The above function is an initializer method for a class that takes in
    two parameters, `x` and `n`, and does not return anything.

    Parameters
    ----------
    `x` : `float`
        The parameter `x` is a float, which means it can hold decimal
        values. It is used to store a numerical value.

    `n` : `int`
        The parameter `n` is an integer that represents the number of
        iterations or steps in a process.
    """

    self.x = x
    self.n = n
multiple property 
multiple: float

The function calculates the product of the variables x and n.

Returns

float The product of self.x and self.n.

n instance-attribute 
n = n
x instance-attribute 
x = x
__repr__ 
__repr__() -> str
Source code in src/mkdocs_demo/config/interfaces.py 
51
52
def __repr__(self) -> str:
    return f"""{self.x} * {self.n} = {self.multiple}"""
__str__ 
__str__() -> str
Source code in src/mkdocs_demo/config/interfaces.py 
48
49
def __str__(self) -> str:
    return f"""x={self.x}, n={self.n}, hence the multiple={self.multiple}"""
from_dict classmethod 
from_dict(d: dict[str, int]) -> Self

The function from_dict takes a dictionary as input, checks if it contains the required keys, and returns an instance of the class with the dictionary values as arguments.

Parameters

d : dict[str, int] The parameter d is a dictionary with string keys and integer values.

Returns

Self The method is returning an instance of the class itself with the attributes specified in the dictionary d.

Source code in src/mkdocs_demo/lib/superfluous.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
@classmethod
def from_dict(cls, d: dict[str, int]) -> Self:
    """
    The function `from_dict` takes a dictionary as input, checks if it
    contains the required keys, and returns an instance of the class with
    the dictionary values as arguments.

    Parameters
    ----------
    `d` : `dict`[`str`, `int`]
        The parameter `d` is a dictionary with string keys and integer
        values.

    Returns
    -------
    `Self`
        The method is returning an instance of the class itself with the
        attributes specified in the dictionary `d`.
    """

    required = ("x", "n")
    obj = {k: v for k, v in d.items()}

    assert obj.keys() in required

    return cls(**obj)

create_trolling 

create_trolling(d: dict[str, int]) -> Trolling

The function create_trolling takes a dictionary d and returns a Trolling object created from the dictionary.

Parameters

d : dict[str, int] A dictionary containing the data needed to create a Trolling object. The keys of the dictionary are strings representing the attributes of the Trolling object, and the values are integers representing the values of those attributes.

Returns

Trolling An instance of the class Trolling.

Source code in src/mkdocs_demo/lib/superfluous.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
def create_trolling(d: dict[str, int]) -> Trolling:
    """
    The function `create_trolling` takes a dictionary `d` and returns a `Trolling` object created from
    the dictionary.

    Parameters
    ----------
    `d` : `dict`[`str`, `int`]
        A dictionary containing the data needed to create a Trolling object. The keys of the dictionary are
    strings representing the attributes of the Trolling object, and the values are integers representing
    the values of those attributes.

    Returns
    -------
    `Trolling`
        An instance of the class Trolling.
    """

    return Trolling.from_dict(d)

scripts

scripts module.

gen_ref_pages

This module generates reference pages for MkDocstrings.

_ module-attribute 

_ = gen_ref_pages(config=RefGenConfig)

mkdocs

This module generates script entrypoints for Poetry related to MkDocs.

build module-attribute 

build = command_factory(
    cmd="mkdocs build --config-file src/mkdocs_demo/mkdocs.yml --clean --use-directory-urls"
)

serve module-attribute 

serve = command_factory(
    cmd="mkdocs serve --config-file src/mkdocs_demo/mkdocs.yml"
)

mypy

This module generates script entrypoints for Poetry related to Mypy typings generation.

gen_types module-attribute 

gen_types = command_factory(
    "stubgen -p mkdocs_demo -o typings"
)

precommit

This module generates script entrypoints for Poetry related to pre-commit.

install module-attribute 

install = command_factory(cmd='pre-commit install')

run module-attribute 

run = command_factory(cmd='pre-commit run --all-files')

update module-attribute 

update = command_factory(cmd='pre-commit autoupdate')