Added mkdocstrings cross-references

Author: tleonhardt

cmd2/ansi.py

@@ -1043,13 +1043,13 @@ def style(
 # These can be altered to suit an application's needs and only need to be a
 # function with the following structure: func(str) -> str
 style_success = functools.partial(style, fg=Fg.GREEN)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify success"""
+"""Partial function supplying arguments to [cmd2.ansi.style][] which colors text to signify success"""
 
 style_warning = functools.partial(style, fg=Fg.LIGHT_YELLOW)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify a warning"""
+"""Partial function supplying arguments to [cmd2.ansi.style][] which colors text to signify a warning"""
 
 style_error = functools.partial(style, fg=Fg.LIGHT_RED)
-"""Partial function supplying arguments to :meth:`cmd2.ansi.style()` which colors text to signify an error"""
+"""Partial function supplying arguments to [cmd2.ansi.style][] which colors text to signify an error"""
 
 
 def async_alert_str(*, terminal_columns: int, prompt: str, line: str, cursor_offset: int, alert_msg: str) -> str:

cmd2/argparse_custom.py

@@ -198,40 +198,28 @@ def my_completer(self, text, line, begidx, endidx, arg_tokens)
 cmd2 has patched ``argparse.Action`` to include the following accessor methods
 for cases in which you need to manually access the cmd2-specific attributes.
 
-- ``argparse.Action.get_choices_callable()`` - See
-  :func:`_action_get_choices_callable` for more details.
-- ``argparse.Action.set_choices_provider()`` - See
-  :func:`_action_set_choices_provider` for more details.
-- ``argparse.Action.set_completer()`` - See
-  :func:`_action_set_completer` for more details.
-- ``argparse.Action.get_descriptive_header()`` - See
-  :func:`_action_get_descriptive_header` for more details.
-- ``argparse.Action.set_descriptive_header()`` - See
-  :func:`_action_set_descriptive_header` for more details.
-- ``argparse.Action.get_nargs_range()`` - See
-  :func:`_action_get_nargs_range` for more details.
-- ``argparse.Action.set_nargs_range()`` - See
-  :func:`_action_set_nargs_range` for more details.
-- ``argparse.Action.get_suppress_tab_hint()`` - See
-  :func:`_action_get_suppress_tab_hint` for more details.
-- ``argparse.Action.set_suppress_tab_hint()`` - See
-  :func:`_action_set_suppress_tab_hint` for more details.
+- ``argparse.Action.get_choices_callable()`` - See `action_get_choices_callable` for more details.
+- ``argparse.Action.set_choices_provider()`` - See `_action_set_choices_provider` for more details.
+- ``argparse.Action.set_completer()`` - See `_action_set_completer` for more details.
+- ``argparse.Action.get_descriptive_header()`` - See `_action_get_descriptive_header` for more details.
+- ``argparse.Action.set_descriptive_header()`` - See `_action_set_descriptive_header` for more details.
+- ``argparse.Action.get_nargs_range()`` - See `_action_get_nargs_range` for more details.
+- ``argparse.Action.set_nargs_range()`` - See `_action_set_nargs_range` for more details.
+- ``argparse.Action.get_suppress_tab_hint()`` - See `_action_get_suppress_tab_hint` for more details.
+- ``argparse.Action.set_suppress_tab_hint()`` - See `_action_set_suppress_tab_hint` for more details.
 
 cmd2 has patched ``argparse.ArgumentParser`` to include the following accessor methods
 
-- ``argparse.ArgumentParser.get_ap_completer_type()`` - See
-  :func:`_ArgumentParser_get_ap_completer_type` for more details.
-- ``argparse.Action.set_ap_completer_type()`` - See
-  :func:`_ArgumentParser_set_ap_completer_type` for more details.
+- ``argparse.ArgumentParser.get_ap_completer_type()`` - See `_ArgumentParser_get_ap_completer_type` for more details.
+- ``argparse.Action.set_ap_completer_type()`` - See `_ArgumentParser_set_ap_completer_type` for more details.
 
 **Subcommand removal**
 
 cmd2 has patched ``argparse._SubParsersAction`` to include a ``remove_parser()``
 method which can be used to remove a subcommand.
 
 ``argparse._SubParsersAction.remove_parser`` - new function which removes a
-sub-parser from a sub-parsers group. See
-:func:`_SubParsersAction_remove_parser` for more details.
+sub-parser from a sub-parsers group. See _SubParsersAction_remove_parser` for more details.
 """
 
 import argparse

cmd2/cmd2.py

@@ -349,7 +349,7 @@ def __init__(
                                        suppressed. Anything written to stderr will still display.
         :param include_py: should the "py" command be included for an embedded Python shell
         :param include_ipy: should the "ipy" command be included for an embedded IPython shell
-        :param allow_cli_args: if ``True``, then :meth:`cmd2.Cmd.__init__` will process command
+        :param allow_cli_args: if ``True``, then [cmd2.Cmd.__init__][] will process command
                                line arguments as either commands to be run or, if ``-t`` or
                                ``--test`` are given, transcript files to run. This should be
                                set to ``False`` if your application parses its own command line
@@ -2446,50 +2446,47 @@ def _raise_keyboard_interrupt(self) -> None:
 
     def precmd(self, statement: Union[Statement, str]) -> Statement:
         """Hook method executed just before the command is executed by
-        :meth:`~cmd2.Cmd.onecmd` and after adding it to history.
+        [cmd2.Cmd.onecmd][] and after adding it to history.
 
         :param statement: subclass of str which also contains the parsed input
         :return: a potentially modified version of the input Statement object
 
-        See :meth:`~cmd2.Cmd.register_postparsing_hook` and
-        :meth:`~cmd2.Cmd.register_precmd_hook` for more robust ways
+        See [cmd2.Cmd.register_postparsing_hook][] and
+        [cmd2.Cmd.register_precmd_hook][] for more robust ways
         to run hooks before the command is executed. See
-        :ref:`features/hooks:Postparsing Hooks` and
-        :ref:`features/hooks:Precommand Hooks` for more information.
+        [Hooks](../features/hooks.md) for more information.
         """
         return Statement(statement) if not isinstance(statement, Statement) else statement
 
     def postcmd(self, stop: bool, statement: Union[Statement, str]) -> bool:
         """Hook method executed just after a command is executed by
-        :meth:`~cmd2.Cmd.onecmd`.
+        [cmd2.Cmd.onecmd][].
 
         :param stop: return `True` to request the command loop terminate
         :param statement: subclass of str which also contains the parsed input
 
-        See :meth:`~cmd2.Cmd.register_postcmd_hook` and :meth:`~cmd2.Cmd.register_cmdfinalization_hook` for more robust ways
+        See [cmd2.Cmd.register_postcmd_hook][] and [cmd2.Cmd.register_cmdfinalization_hook][] for more robust ways
         to run hooks after the command is executed. See
-        :ref:`features/hooks:Postcommand Hooks` and
-        :ref:`features/hooks:Command Finalization Hooks` for more information.
+        [Hooks](../features/hooks.md) for more information.
         """
         return stop
 
     def preloop(self) -> None:
-        """Hook method executed once when the :meth:`~.cmd2.Cmd.cmdloop()`
+        """Hook method executed once when the [cmd2.Cmd.cmdloop][]
         method is called.
 
-        See :meth:`~cmd2.Cmd.register_preloop_hook` for a more robust way
+        See [cmd2.Cmd.register_preloop_hook][] for a more robust way
         to run hooks before the command loop begins. See
-        :ref:`features/hooks:Application Lifecycle Hooks` for more information.
+        [Hooks](../features/hooks.md) for more information.
         """
         pass
 
     def postloop(self) -> None:
-        """Hook method executed once when the :meth:`~.cmd2.Cmd.cmdloop()`
-        method is about to return.
+        """Hook method executed once when the [cmd2.Cmd.cmdloop][] method is about to return.
 
-        See :meth:`~cmd2.Cmd.register_postloop_hook` for a more robust way
+        See [cmd2.Cmd.register_postloop_hook][] for a more robust way
         to run hooks after the command loop completes. See
-        :ref:`features/hooks:Application Lifecycle Hooks` for more information.
+        [Hooks](../features/hooks.md) for more information.
         """
         pass
 
@@ -3028,9 +3025,11 @@ def cmd_func(self, command: str) -> Optional[CommandFunc]:
 
         :param command: the name of the command
 
-        :Example:
+        Example:
 
-        >>> helpfunc = self.cmd_func('help')
+        ```py
+        helpfunc = self.cmd_func('help')
+        ```
 
         helpfunc now contains a reference to the ``do_help`` method
         """

cmd2/decorators.py

@@ -43,15 +43,17 @@ def with_category(category: str) -> Callable[[CommandFunc], CommandFunc]:
     :param category: the name of the category in which this command should
                      be grouped when displaying the list of commands.
 
-    :Example:
+    Example:
 
-    >>> class MyApp(cmd2.Cmd):
-    >>>   @cmd2.with_category('Text Functions')
-    >>>   def do_echo(self, args)
-    >>>     self.poutput(args)
+    ```py
+    class MyApp(cmd2.Cmd):
+        @cmd2.with_category('Text Functions')
+        def do_echo(self, args)
+            self.poutput(args)
+    ```
 
     For an alternative approach to categorizing commands using a function, see
-    :func:`~cmd2.utils.categorize`
+    [cmd2.utils.categorize][]
     """
 
     def cat_decorator(func: CommandFunc) -> CommandFunc:
@@ -152,12 +154,13 @@ def with_argument_list(
     :param preserve_quotes: if ``True``, then argument quotes will not be stripped
     :return: function that gets passed a list of argument strings
 
-    :Example:
-
-    >>> class MyApp(cmd2.Cmd):
-    >>>     @cmd2.with_argument_list
-    >>>     def do_echo(self, arglist):
-    >>>         self.poutput(' '.join(arglist)
+    Example:
+    ```py
+    class MyApp(cmd2.Cmd):
+        @cmd2.with_argument_list
+        def do_echo(self, arglist):
+            self.poutput(' '.join(arglist)
+    ```
     """
     import functools
 
@@ -285,38 +288,41 @@ def with_argparser(
     :param preserve_quotes: if ``True``, then arguments passed to argparse maintain their quotes
     :param with_unknown_args: if true, then capture unknown args
     :return: function that gets passed argparse-parsed args in a ``Namespace``
-             A :class:`cmd2.argparse_custom.Cmd2AttributeWrapper` called ``cmd2_statement`` is included
-             in the ``Namespace`` to provide access to the :class:`cmd2.Statement` object that was created when
+             A [cmd2.argparse_custom.Cmd2AttributeWrapper][] called ``cmd2_statement`` is included
+             in the ``Namespace`` to provide access to the [cmd2.Statement][] object that was created when
              parsing the command line. This can be useful if the command function needs to know the command line.
 
-    :Example:
-
-    >>> parser = cmd2.Cmd2ArgumentParser()
-    >>> parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
-    >>> parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
-    >>> parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
-    >>> parser.add_argument('words', nargs='+', help='words to print')
-    >>>
-    >>> class MyApp(cmd2.Cmd):
-    >>>     @cmd2.with_argparser(parser, preserve_quotes=True)
-    >>>     def do_argprint(self, args):
-    >>>         "Print the options and argument list this options command was called with."
-    >>>         self.poutput(f'args: {args!r}')
-
-    :Example with unknown args:
-
-    >>> parser = cmd2.Cmd2ArgumentParser()
-    >>> parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
-    >>> parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
-    >>> parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
-    >>>
-    >>> class MyApp(cmd2.Cmd):
-    >>>     @cmd2.with_argparser(parser, with_unknown_args=True)
-    >>>     def do_argprint(self, args, unknown):
-    >>>         "Print the options and argument list this options command was called with."
-    >>>         self.poutput(f'args: {args!r}')
-    >>>         self.poutput(f'unknowns: {unknown}')
-
+    Example:
+
+    ```py
+    parser = cmd2.Cmd2ArgumentParser()
+    parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
+    parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
+    parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
+    parser.add_argument('words', nargs='+', help='words to print')
+
+    class MyApp(cmd2.Cmd):
+        @cmd2.with_argparser(parser, preserve_quotes=True)
+        def do_argprint(self, args):
+            "Print the options and argument list this options command was called with."
+            self.poutput(f'args: {args!r}')
+    ```
+
+    Example with unknown args:
+
+    ```py
+    parser = cmd2.Cmd2ArgumentParser()
+    parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
+    parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
+    parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
+
+    class MyApp(cmd2.Cmd):
+        @cmd2.with_argparser(parser, with_unknown_args=True)
+        def do_argprint(self, args, unknown):
+            "Print the options and argument list this options command was called with."
+            self.poutput(f'args: {args!r}')
+            self.poutput(f'unknowns: {unknown}')
+    ```
     """
     import functools
 

cmd2/history.py

@@ -150,13 +150,13 @@ def from_dict(source_dict: Dict[str, Any]) -> 'HistoryItem':
 
 
 class History(List[HistoryItem]):
-    """A list of :class:`~cmd2.history.HistoryItem` objects with additional methods
+    """A list of [HistoryItem][cmd2.history.HistoryItem] objects with additional methods
     for searching and managing the list.
 
-    :class:`~cmd2.Cmd` instantiates this class into the :data:`~cmd2.Cmd.history`
+    [cmd2.Cmd][] instantiates this class into the `cmd2.Cmd.history`
     attribute, and adds commands to it as a user enters them.
 
-    See :ref:`features/history:History` for information about the built-in command
+    See [History](../features/history.md) for information about the built-in command
     which allows users to view, search, run, and save previously entered commands.
 
     Developers interested in accessing previously entered commands can use this
@@ -207,7 +207,7 @@ def get(self, index: int) -> HistoryItem:
         """Get item from the History list using 1-based indexing.
 
         :param index: optional item to get
-        :return: a single :class:`~cmd2.history.HistoryItem`
+        :return: a single [cmd2.history.HistoryItem][]
         """
         if index == 0:
             raise IndexError('The first command in history is command 1.')