31: Add Documentation

.readthedocs.yml

@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: docs/conf.py
+
+formats:
+  - pdf
+  - epub
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

ItsPrompt/data/checkbox.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 
 from ..objects.prompts.option import Option
-from ..objects.prompts.options_with_seperator import OptionsWithSeparator
+from ..objects.prompts.options_with_separator import OptionsWithSeparator
 from ..objects.prompts.separator import Separator
 from ..objects.prompts.type import OptionsList
 

ItsPrompt/data/expand.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 
 from ..objects.prompts.option import Option
-from ..objects.prompts.options_with_seperator import OptionsWithSeparator
+from ..objects.prompts.options_with_separator import OptionsWithSeparator
 from ..objects.prompts.separator import Separator
 from ..objects.prompts.type import OptionsList
 

ItsPrompt/data/select.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 
 from ItsPrompt.objects.prompts.option import Option
-from ItsPrompt.objects.prompts.options_with_seperator import OptionsWithSeparator
+from ItsPrompt.objects.prompts.options_with_separator import OptionsWithSeparator
 from ItsPrompt.objects.prompts.separator import Separator
 from ItsPrompt.objects.prompts.type import OptionsList
 

ItsPrompt/data/style.py

@@ -32,9 +32,12 @@ class PromptStyle:
     disabled="fg:ansibrightblack",
     separator="fg:ansibrightgreen",
 )
+"""
+The default style for the prompts.
+"""
 
 
-def convert_style(style: PromptStyle) -> Style:
+def _convert_style(style: PromptStyle) -> Style:
     """
     Converts the given `PromptStyle` to a usable `Style` object.
 
@@ -48,7 +51,7 @@ def convert_style(style: PromptStyle) -> Style:
 
 def create_from_default() -> PromptStyle:
     """
-    Returns a copy of the default style, which can be edited without changing the default style.
+    Returns a copy of the :data:`default_style` which can be edited without changing the default style.
 
     :return: An editable copy of the default style
     :rtype: PromptStyle

ItsPrompt/objects/prompts/separator.py

@@ -1,4 +1,14 @@
 class Separator:
+    """
+    Used for creating distinctive sections in the prompt types:
+
+    - :meth:`~ItsPrompt.prompt.Prompt.select`
+    - :meth:`~ItsPrompt.prompt.Prompt.raw_select`
+    - :meth:`~ItsPrompt.prompt.Prompt.checkbox`
+    - :meth:`~ItsPrompt.prompt.Prompt.expand`
+
+    It is purely cosmetic.
+    """
 
     def __init__(self, label: str):
         """

ItsPrompt/objects/prompts/type.py

@@ -1,9 +1,50 @@
 from ItsPrompt.objects.prompts.separator import Separator
 
-CompletionDict = dict[str, "CompletionDict | None"]
+OptionWithId = tuple[str, str, str | None]
+"""
+The OptionWithId tuple is used to store an option, its id and an optional key (for expand prompt).
 
-TablePromptDict = dict[str, list[str]]
-TablePromptList = list[list[str]]
+For all prompts excluding :meth:`~ItsPrompt.prompt.Prompt.expand`, the tuple is structured as follows
+
+- The first element is the displayed option
+- The second element is the id of the option
+
+For the :meth:`~ItsPrompt.prompt.Prompt.expand` prompt, the tuple is structured as follows:
+
+- The first element is the key of the option
+- The second element is the displayed option
+- The third element is the id of the option
+"""
 
-OptionWithId = tuple[str, str, str | None]
 OptionsList = tuple[str | OptionWithId | Separator, ...]
+"""
+Different types of options that can be used in a prompt.
+
+Can be given by either:
+
+- A :class:`str`, which is the displayed option and its id
+- A :class:`tuple` containing the displayed option, its id and an optional key (for expand prompt)
+- A :class:`~ItsPrompt.objects.prompts.separator.Separator` instance
+"""
+
+TablePromptList = list[list[str]]
+"""
+A type hint for the :class:`list` structure used to represent a table prompt.
+
+Each inner :class:`list` represents a row in the table.
+
+The cells are represented by the :class:`str` type.
+
+"""
+
+TablePromptDict = dict[str, list[str]]
+"""
+A type hint for the :class:`dict` structure used to represent a table prompt.
+
+The keys are the column names and the values are the cells in the column.
+"""
+
+CompletionDict = dict[str, "CompletionDict | None"]
+"""
+A type hint for the :class:`dict` structure used to represent the completion dictionary.
+"""

ItsPrompt/prompt.py

@@ -1,5 +1,6 @@
 """
-# ItsPrompt
+ItsPrompt
+=========
 
 created by ItsNameless
 
@@ -28,7 +29,7 @@
     MultiColumnCompletionsMenu,
 )
 
-from .data.style import PromptStyle, convert_style, default_style
+from .data.style import PromptStyle, _convert_style, default_style
 from .keyboard_handler import generate_key_bindings
 from .objects.prompts.type import CompletionDict, TablePromptDict, TablePromptList, OptionsList
 from .prompts.checkbox import CheckboxPrompt
@@ -65,7 +66,7 @@ def select(
         style: PromptStyle | None = None,
     ) -> str:
         """
-        Ask the user for selecting ONE of the given `options`.
+        Ask the user for selecting **one** of the given `options`.
 
         This method shows the question alongside the `options` as a nice list. The user has the ability to use the
         up, down and enter keys to navigate between the options and select the one that is right.
@@ -102,7 +103,7 @@ def select(
             ),
             key_bindings=generate_key_bindings(SelectPrompt),
             erase_when_done=True,
-            style=convert_style(style) if style else convert_style(default_style),
+            style=_convert_style(style) if style else _convert_style(default_style),
         )
         ans = app.prompt()
         if ans == None:
@@ -120,7 +121,7 @@ def raw_select(
         style: PromptStyle | None = None,
     ) -> str:
         """
-        Ask the user for selection ONE of the given `options`.
+        Ask the user for selecting **one** of the given `options`.
 
         This method shows the question alongside the `options` as a nice list. The user needs to type the index of
         the answer. If `allow_keyboard` is given, the user may use the keyboard as in the `select()` method.
@@ -159,7 +160,7 @@ def raw_select(
             ),
             key_bindings=generate_key_bindings(RawSelectPrompt),
             erase_when_done=True,
-            style=convert_style(style) if style else convert_style(default_style),
+            style=_convert_style(style) if style else _convert_style(default_style),
         )
         ans = app.prompt()
         if ans is None:
@@ -177,7 +178,7 @@ def expand(
         style: PromptStyle | None = None,
     ) -> str:
         """
-        Ask the user for selecting ONE of the given `options`.
+        Ask the user for selecting **one** of the given `options`.
 
         The user needs to type the key of the option. If the user types `h`, all options will be shown.
 
@@ -219,7 +220,7 @@ def expand(
             ),
             key_bindings=generate_key_bindings(ExpandPrompt),
             erase_when_done=True,
-            style=convert_style(style) if style else convert_style(default_style),
+            style=_convert_style(style) if style else _convert_style(default_style),
         )
         ans = app.prompt()
         if ans is None:
@@ -238,7 +239,7 @@ def checkbox(
         style: PromptStyle | None = None,
     ) -> list[str]:
         """
-        Ask the user for selecting MULTIPLE of the given `options`.
+        Ask the user for selecting **multiple** of the given `options`.
 
         The `options` will be shown as a nice list. The user may navigate with up and down, select or deselect with
         space and submit with enter.
@@ -281,7 +282,7 @@ def checkbox(
             ),
             key_bindings=generate_key_bindings(CheckboxPrompt),
             erase_when_done=True,
-            style=convert_style(style) if style else convert_style(default_style),
+            style=_convert_style(style) if style else _convert_style(default_style),
         )
         ans = app.prompt()
         if ans == None:
@@ -335,7 +336,7 @@ def confirm(
             ),
             key_bindings=generate_key_bindings(ConfirmPrompt),
             erase_when_done=True,
-            style=convert_style(style) if style else convert_style(default_style),
+            style=_convert_style(style) if style else _convert_style(default_style),
         )
 
         ans = app.prompt()
@@ -359,30 +360,32 @@ def input(
         """
         Ask the user for typing an input.
 
-        If default is given, it will be returned if enter was pressed and no input was given by the user. If the user
-        writes an input, the default will be overwritten.
+        If :data:`default` is given, it will be returned if enter was pressed and no input was given by the user. If the user
+        writes an input, the :data:`default` will be overwritten.
 
-        If multiline is activated, enter will not submit, but rather create a newline. Use `alt+enter` to submit.
+        If :data:`multiline` is activated, enter will not submit, but rather create a newline. Use ``alt+enter`` to submit.
 
-        If show_symbol is given, all chars (except newlines) will be replaced with this character in the interface.
-        The result will still be the input the user typed, it just will not appear in the CLI.
+        If :data:`show_symbol` is given, all chars (except newlines) will be replaced with this character in the interface.
+        The result will still be the input the user typed, it just will not appear in the CLI. This is useful for
+        password inputs.
 
-        Validate takes a function which receives a `str` (the current input of the user) and may return None, a
-        `str` or simply a boolean value.
+        :data:`validate` takes a function which receives a :class:`str` (the current input of the user) and may 
+        return :class:`None`, a :class:`str` or simply a boolean value.
 
-        If the function returns None (or True), the prompt may assume that the input is
+        If the function returns :class:`None` (or ``True``), the prompt may assume that the input is
         valid.
 
-        If it returns a `str`, this will be the error shown to the user. If it returns `False`, the error shown will
-        simply be a general error statement without additional information. The user will not be able to submit the
-        input, if validate returns an error.
+        If it returns a :class:`str`, this will be the error shown to the user. If it returns ``False``, the error 
+        shown will simply be a general error statement without additional information. The user will not be able to 
+        submit the input, if :data:`validate` returns an error.
 
-        Completions may be a list of possible completion strings or a nested dictionary where the key is a completion
-        string and the value is a new dict in the same style (more in the README.md).
+        :data:`completions` may be a list of possible completion strings or a nested dictionary where the key is a 
+        completion string and the value is a new dict in the same style (more in the README.md).
 
-        You can use your own Completer as well (more in the README.md).
+        You can use your own :class:`Completer` as well (more in the README.md).
 
-        THESE VALUES ARE MUTUALLY EXCLUSIVE. You may not use both. If you use a completer, you can not use show_symbol!
+        :data:`completions` **and** :data:`completer` **are mutually exclusive!** You may not use both. If you use a :data:`completer`, you can not use 
+        :data:`show_symbol`!
 
         :param question: The question to display
         :type question: str
@@ -402,7 +405,7 @@ def input(
         :type completion_show_multicolumn: bool, optional
         :param style: A separate style to style the prompt (empty or None for default style), defaults to None
         :type style: PromptStyle | None, optional
-        :raises KeyboardInterrupt: When the user presses ctrl-c, `KeyboardInterrupt` will be raised
+        :raises KeyboardInterrupt: When the user presses ctrl-c, :class:`KeyboardInterrupt` will be raised
         :return: The input of the user
         :rtype: str
         """
@@ -453,11 +456,11 @@ def input(
             ),
             key_bindings=generate_key_bindings(InputPrompt),
             erase_when_done=True,
-            style=convert_style(style) if style else convert_style(default_style),
+            style=_convert_style(style) if style else _convert_style(default_style),
         )
 
         ans = app.prompt()
-        if ans == None:
+        if ans is None:
             raise KeyboardInterrupt()
         return ans
 
@@ -472,10 +475,10 @@ def table(
         Ask the user for filling out the displayed table.
 
         This method shows the question alongside a table, which the user may navigate with the arrow keys. The user
-        has the ability to use the up, down and enter keys to navigate between the options and change the text in
+        can use the up, down and enter keys to navigate between the options and change the text in
         each cell.
 
-        The `data` is either a pandas DataFrame, a list or a dictionary (more in the README.md).
+        The `data` is either a :class:`pandas.DataFrame`, a :class:`list` or a :class:`dict` (more in the README.md).
 
         :param question: The question to display
         :type question: str
@@ -485,7 +488,7 @@ def table(
         :type style: PromptStyle | None, optional
         :raises KeyboardInterrupt: When the user presses ctrl-c, `KeyboardInterrupt` will be raised
         :return: The id of the selected option
-        :rtype: str
+        :rtype: DataFrame | TablePromptDict | TablePromptList
         """
         app = TablePrompt(
             question,
@@ -510,7 +513,7 @@ def table(
             ),
             key_bindings=generate_key_bindings(TablePrompt),
             erase_when_done=True,
-            style=convert_style(style) if style else convert_style(default_style),
+            style=_convert_style(style) if style else _convert_style(default_style),
         )
         ans = app.prompt()
         # if type(ans) is type(None):