fix docs hyperlinks (#133)

.gitignore

@@ -7,6 +7,7 @@ __pycache__/
 /build/
 /dist/
 /docs/build/
+/docs/contributing.md
 
 # Unit test / coverage reports
 /.coverage*

docs/pydoc-markdown.yml

@@ -5,6 +5,9 @@ processors:
 - type: filter
 - type: pydoc_markdown_shtab.ShtabProcessor
 - type: crossref
+hooks:
+  pre-render:
+  - sed 's#](./#](https://github.com/iterative/shtab/tree/main/#g' ../CONTRIBUTING.md > contributing.md
 renderer:
   type: mkdocs
   markdown:
@@ -37,7 +40,7 @@ renderer:
       href: https://github.com/iterative/shtab/issues?q=
   - title: Contributing
     name: contributing
-    source: ../CONTRIBUTING.md
+    source: contributing.md
   - title: Licence
     name: licence
     source: ../LICENCE

docs/pydoc_markdown_shtab.py

@@ -8,10 +8,10 @@ def _process(self, node):
         if not getattr(node, "docstring", None):
             return super()._process(node)
         # convert parameter lists to markdown list
-        node.docstring.content = re.sub(
-            r"^(\w+)\s{2,}(:.*?)$",
-            r"* __\1__*\2*  ",
-            node.docstring.content,
-            flags=re.M,
-        )
+        node.docstring.content = re.sub(r"^(\w+)(:.*?)$", r"* __\1__\2", node.docstring.content,
+                                        flags=re.M)
+        # fix code cross-references
+        node.docstring.content = re.sub(r"<../(\S+)>",
+                                        r"[\1](https://github.com/iterative/shtab/tree/main/\1)",
+                                        node.docstring.content, flags=re.M)
         return super()._process(node)

shtab/__init__.py

@@ -755,14 +755,15 @@ def recurse_parser(cparser, positional_idx, requirements=None):
 def complete(parser: ArgumentParser, shell: str = "bash", root_prefix: Opt[str] = None,
              preamble: Union[str, Dict] = "", choice_functions: Opt[Any] = None) -> str:
     """
-    parser  : argparse.ArgumentParser
-    shell  : str (bash/zsh)
-    root_prefix  : str or `None`
+    shell:
+      bash/zsh/tcsh
+    root_prefix:
       prefix for shell functions to avoid clashes (default: "_{parser.prog}")
-    preamble  : dict or str
+    preamble:
       mapping shell to text to prepend to generated script
       (e.g. `{"bash": "_myprog_custom_function(){ echo hello }"}`)
-    choice_functions  : deprecated
+    choice_functions:
+      *deprecated*
 
     N.B. `parser.add_argument().complete = ...` can be used to define custom
     completions (e.g. filenames). See <../examples/pathcomplete.py>.
@@ -778,7 +779,7 @@ def complete(parser: ArgumentParser, shell: str = "bash", root_prefix: Opt[str]
     )
 
 
-def completion_action(parent=None, preamble=""):
+def completion_action(parent: Opt[ArgumentParser] = None, preamble: Union[str, Dict] = ""):
     class PrintCompletionAction(_ShtabPrintCompletionAction):
         def __call__(self, parser, namespace, values, option_string=None):
             print(complete(parent or parser, values, preamble=preamble))
@@ -788,19 +789,17 @@ def __call__(self, parser, namespace, values, option_string=None):
 
 
 def add_argument_to(
-    parser,
-    option_string="--print-completion",
-    help="print shell completion script",
-    parent=None,
-    preamble="",
+    parser: ArgumentParser,
+    option_string: Union[str, List[str]] = "--print-completion",
+    help: str = "print shell completion script",
+    parent: Opt[ArgumentParser] = None,
+    preamble: Union[str, Dict] = "",
 ):
     """
-    parser  : argparse.ArgumentParser
-    option_string  : str or list[str]
+    option_string:
       iff positional (no `-` prefix) then `parser` is assumed to actually be
       a subparser (subcommand mode)
-    help  : str
-    parent  : argparse.ArgumentParser
+    parent:
       required in subcommand mode
     """
     if isinstance(option_string, str):