Skip to content

shellman ¤

shellman package.

Read documentation from shell script comments and render it with templates.

shellman reads specified FILEs and searches for special comments beginning with two sharps (##). It extracts documentation from these comment lines, and then generate a document by rendering a template. The template rendering is done with Jinja2. See https://jinja.palletsprojects.com/en/3.1.x/.

Modules:

  • cli –

    Module that contains the command line application.

  • context –

    Jinja-context related utilities.

  • debug –

    Debugging utilities.

  • reader –

    Module to read a file/stream and pre-process the documentation lines.

  • tags –

    Section module.

  • templates –

    This module contains our definitions of templates.

Classes:

  • DocFile –

    A shell script or documentation file.

  • DocStream –

    A stream of shell code or documentation.

  • Template –

    Shellman templates.

DocFile ¤

DocFile(path: str)

A shell script or documentation file.

Parameters:

  • path (str) –

    The path to the file.

Source code in src/shellman/reader.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def __init__(self, path: str) -> None:
    """Initialize the documentation file.

    Parameters:
        path: The path to the file.
    """
    self.filepath = path
    self.filename = os.path.basename(path)
    with open(path, encoding="utf-8") as stream:
        try:
            self.sections = _process_blocks(_preprocess_lines(_preprocess_stream(stream)))
        except UnicodeDecodeError:
            logger.error(f"Cannot read file {path}")  # noqa: TRY400
            self.sections = {}

DocStream ¤

DocStream(stream: Iterable[str], filename: str = '')

A stream of shell code or documentation.

Parameters:

  • stream (Iterable[str]) –

    A text stream.

  • filename (str, default: '' ) –

    An optional file name.

Source code in src/shellman/reader.py 
159
160
161
162
163
164
165
166
167
168
def __init__(self, stream: Iterable[str], filename: str = "") -> None:
    """Initialize the documentation file.

    Parameters:
        stream: A text stream.
        filename: An optional file name.
    """
    self.filepath = None
    self.filename = filename
    self.sections = _process_blocks(_preprocess_lines(_preprocess_stream(stream)))

Template ¤

Template(
    env_or_directory: str | Environment,
    base_template: str,
    context: dict[str, Any] | None = None,
    filters: dict[str, Any] | None = None,
)

Shellman templates.

Parameters:

  • env_or_directory (str | Environment) –

    Jinja environment or directory to load environment from.

  • base_template (str) –

    The template file to use.

  • context (dict[str, Any] | None, default: None ) –

    Base context to render with.

  • filters (dict[str, Any] | None, default: None ) –

    Base filters to add to the environment.

Methods:

  • render –

    Render the template.

Attributes:

Source code in src/shellman/templates/__init__.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def __init__(
    self,
    env_or_directory: str | Environment,
    base_template: str,
    context: dict[str, Any] | None = None,
    filters: dict[str, Any] | None = None,
):
    """Initialize the template.

    Parameters:
        env_or_directory: Jinja environment or directory to load environment from.
        base_template: The template file to use.
        context: Base context to render with.
        filters: Base filters to add to the environment.
    """
    if isinstance(env_or_directory, Environment):
        self.env = env_or_directory
    elif isinstance(env_or_directory, str):
        self.env = _get_env(env_or_directory)
    else:
        raise TypeError(env_or_directory)

    if filters is None:
        filters = {}

    self.env.filters.update(FILTERS)
    self.env.filters.update(filters)
    self.base_template = base_template
    self.context = context or {}
    self.__template: Template = None  # type: ignore[assignment]

template property ¤

template: Template

The corresponding Jinja template.

render ¤

render(**kwargs: Any) -> str

Render the template.

Parameters:

  • **kwargs (Any, default: {} ) –

    Keyword arguments passed to Jinja's render method.

Returns:

  • str –

    The rendered text.

Source code in src/shellman/templates/__init__.py 
80
81
82
83
84
85
86
87
88
89
90
91
92
def render(self, **kwargs: Any) -> str:
    """Render the template.

    Parameters:
        **kwargs: Keyword arguments passed to Jinja's render method.


    Returns:
        The rendered text.
    """
    context = deepcopy(self.context)
    context.update(kwargs)
    return self.template.render(**context).rstrip("\n")