Add API reference

docs/reference/jcloud_docsgen/utils.md

@@ -0,0 +1,335 @@
+# Module `jcloud_docsgen.utils`
+
+The utilities for jcloud_docsgen
+
+## Class `ExistingDirectory`
+
+pathlib.Path subclass that is a directory.
+
+ExistingDirectory represents a filesystem path but it also checks
+whether the path exists and is not a file but a directory. It
+inherits from pathlib.Path.
+
+### Base classes
+
+- `pathlib.Path`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, path, *args, **kwargs) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `path` | -- | normal | -- | -- |
+| `args` | -- | vararg | -- | -- |
+| `kwargs` | -- | kwargs | -- | -- |
+
+
+
+
+
+### Docstring
+
+pathlib.Path subclass that is a directory.
+
+ExistingDirectory represents a filesystem path but it also checks
+whether the path exists and is not a file but a directory. It
+inherits from pathlib.Path.
+
+## Class `ExistingFile`
+
+pathlib.Path subclass that is a file.
+
+ExistingFile represents a filesystem path but it also checks whether
+the path exists and is not a directory but a file. It inherits from
+pathlib.Path.
+
+### Base classes
+
+- `pathlib.Path`
+
+### Body
+
+#### Constructor (method `__init__`)
+
+##### Method signature
+
+```python
+__init__(self, path, *args, **kwargs) -> None
+```
+
+##### Returns
+
+Return type: `None`
+
+##### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `self` | -- | normal | -- | -- |
+| `path` | -- | normal | -- | -- |
+| `args` | -- | vararg | -- | -- |
+| `kwargs` | -- | kwargs | -- | -- |
+
+
+
+
+
+### Docstring
+
+pathlib.Path subclass that is a file.
+
+ExistingFile represents a filesystem path but it also checks whether
+the path exists and is not a directory but a file. It inherits from
+pathlib.Path.
+
+## Function `_quote`
+
+Quotes a string.
+
+
+### Function signature
+
+```python
+_quote(string: str, quotation_mark: str) -> str
+```
+
+### Returns
+
+The quoted string
+
+Return type: `str`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `string` | `str` | normal | -- | The string to quote |
+| `quotation_mark` | `str` | normal | -- | The quotation mark |
+
+
+
+
+
+
+
+### Docstring
+
+Quotes a string.
+
+:param string: The string to quote
+:type string: str
+:param quotation_mark: The quotation mark
+:type quotation_mark: str
+
+:return: The quoted string
+:rtype: str
+
+## Function `human_readable_list`
+
+Generates a human-readable list from a list.
+
+
+### Function signature
+
+```python
+human_readable_list(ls: list, final_separator: str = 'and', quotation_mark: str = '') -> str
+```
+
+### Returns
+
+The human-readable list.
+
+Return type: `str`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `ls` | `list` | normal | -- | The list. |
+| `final_separator` | `str` | normal | `'and'` | The seperator between the last and the second-to-last element of the list. Default is 'and'. |
+| `quotation_mark` | `str` | normal | `''` | The characters that are inserted before and after an element. Default is ''. |
+
+
+
+
+
+
+
+### Docstring
+
+Generates a human-readable list from a list.
+
+:param ls: The list.
+:type ls: list
+:param final_separator: The seperator between the last and the
+                        second-to-last element of the list. Default
+                        is 'and'.
+:type final_separator: str
+:param quotation_mark: The characters that are inserted before and
+                       after an element. Default is ''.
+
+:return: The human-readable list.
+:rtype: str
+
+## Function `_list_type_names`
+
+Converts a list of types into a list of their names (``__name__``
+attribute)
+
+### Function signature
+
+```python
+_list_type_names(types: list[type]) -> list[str]
+```
+
+### Returns
+
+The list of the names of the types
+
+Return type: `list[str]`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `types` | `list[type]` | normal | -- | The list of types |
+
+
+
+
+
+
+
+### Docstring
+
+Converts a list of types into a list of their names (``__name__``
+attribute)
+
+:param types: The list of types
+:type types: list[type]
+
+:return: The list of the names of the types
+:rtype: list[str]
+
+## Function `assert_that_is_instance`
+
+### Function signature
+
+```python
+assert_that_is_instance(obj: object, class_or_tuple: Union[type, types.UnionType, tuple[type, ...]]) -> None
+```
+
+### Returns
+
+Return type: `None`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `obj` | `object` | normal | -- | -- |
+| `class_or_tuple` | `Union[type, types.UnionType, tuple[type, ...]]` | normal | -- | -- |
+
+## Function `non_empty_str`
+
+Returns the value or ``None``.
+
+Returns the value if it is not empty and not `Ǹone``; otherwise,
+returns ``None``.
+Please note: values are stripped, i. e. if the value consists only
+             of spaces, it is also considered empty.
+
+### Function signature
+
+```python
+non_empty_str(value: Union[str, None]) -> Union[str, None]
+```
+
+### Returns
+
+The value or ``None``.
+
+Return type: `Union[str, None]`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `Union[str, None]` | normal | -- | The value. |
+
+
+
+
+
+
+
+### Docstring
+
+Returns the value or ``None``.
+
+Returns the value if it is not empty and not `Ǹone``; otherwise,
+returns ``None``.
+Please note: values are stripped, i. e. if the value consists only
+             of spaces, it is also considered empty.
+
+:param value: The value.
+:type value: Union[str, None]
+
+:return: The value or ``None``.
+:rtype: Union[str, None]
+
+## Function `get_relative_path_segments`
+
+Returns the path segments relative to ``root``.
+
+
+### Function signature
+
+```python
+get_relative_path_segments(path: pathlib.Path, root: pathlib.Path) -> list[str]
+```
+
+### Returns
+
+The path segments relative to ``root``.
+
+Return type: `list[str]`
+
+### Parameters
+
+| Parameter | Type | Kind | Default value | Description |
+| --- | --- | --- | --- | --- |
+| `path` | `pathlib.Path` | normal | -- | The path. |
+| `root` | `pathlib.Path` | normal | -- | The root path. |
+
+
+
+
+
+
+
+### Docstring
+
+Returns the path segments relative to ``root``.
+
+:param path: The path.
+:type path: pathlib.Path
+:param root: The root path.
+:type root: pathlib.Path
+
+:return: The path segments relative to ``root``.
+:rtype: list[str]