feat: implement mkdocs

CHANGELOG.md

@@ -1,3 +1,5 @@
+# Changelog
+
 # 0.0.0 (YYYY-MM-DD)
 
  - TBD

Makefile

@@ -121,9 +121,6 @@ mkdocs: install $(MKDOCS_INDEX)
 $(MKDOCS_INDEX): docs/requirements.txt mkdocs.yml docs/*.md
 	@ mkdir -p docs/about
 	@ cd docs && ln -sf ../README.md index.md
-	@ cd docs/about && ln -sf ../../CHANGELOG.md changelog.md
-	@ cd docs/about && ln -sf ../../CONTRIBUTING.md contributing.md
-	@ cd docs/about && ln -sf ../../LICENSE.md license.md
 	poetry run mkdocs build --clean --strict
 
 # Workaround: https://github.com/rtfd/readthedocs.org/issues/5090

README.md

@@ -1,15 +1,15 @@
 # Overview
 
-A wrapper around argparser to help build CLIs from functions. Uses typehints extensively.
+A wrapper around argparser to help build CLIs from functions. Uses type-hints extensively :snake:.
 
 [![PyPi Version](https://img.shields.io/pypi/v/arger.svg?style=flat)](https://pypi.python.org/pypi/arger)
 [![Python Version](https://img.shields.io/pypi/pyversions/returns.svg)](https://pypi.org/project/arger/)
 ![](https://github.com/jnoortheen/arger/workflows/test-and-publish/badge.svg)
 [![PyPI License](https://img.shields.io/pypi/l/arger.svg)](https://pypi.org/project/arger)
 
-# Setup
+# Setup 
 
-## Installation
+## :gear: Installation
 
 Install it directly into an activated virtual environment:
 
@@ -23,8 +23,9 @@ or add it to your [Poetry](https://poetry.eustace.io/) project:
 $ poetry add arger
 ```
 
-# Usage
+# :books: Usage
 - create a python file called test.py
+
 ```python
 from arger import Arger
 
@@ -43,11 +44,11 @@ if __name__ == '__main__':
 
 - run this normally with 
 
-```shell script
-$ python test.py 100 param2
+```sh
+python test.py 100 param2
 ```
 
-- Checkout [examples](./tests/examples) folder and documentation to see more of `arger` in action.
+- Checkout [examples](docs/examples) folder and documentation to see more of `arger` in action.
 
 # Alternatives
 

arger/parser/classes.py

@@ -26,8 +26,9 @@ def __init__(
         Tries to be compatible to `ArgumentParser.add_argument
         https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_argument`_.
 
-        :param flags: Either a name or a list of option strings, e.g. -f, --foo.
-        :param default: The value produced if the argument is absent from the command line.
+        Args:
+            flags: Either a name or a list of option strings, e.g. -f, --foo.
+            default: The value produced if the argument is absent from the command line.
             * The default value assigned to a keyword argument helps determine
                 the type of option and action.
             * The default value is assigned directly to the parser's default for that option.
@@ -37,18 +38,18 @@ def __init__(
                 * If the default value is a list, the action is append
                 (multiple instances of that option are permitted).
                 * Strings or None imply a store action.
-        :param type: The type to which the command-line argument should be converted.
-        :param help: A brief description of what the argument does.
-        :param metavar: A name for the argument in usage messages.
-        :param required: Whether or not the command-line option may be omitted (optionals only).
-        :param kwargs: will be passed onto parser.add_argument
-
-        :param nargs: The number of command-line arguments that should be consumed. nargs: to be generated from the type
-        :param dest: The name of the attribute to be added to the object returned by parse_args().
-        :param const: covered by type-hint and default value given
-        :param choices: covered by enum type
-
-        :param action: The basic type of action to be taken when this argument is encountered at the command line.
+            type: The type to which the command-line argument should be converted.
+            help: A brief description of what the argument does.
+            metavar: A name for the argument in usage messages.
+            required: Whether or not the command-line option may be omitted (optionals only).
+            kwargs: will be passed onto parser.add_argument
+
+            nargs: The number of command-line arguments that should be consumed. nargs: to be generated from the type
+            dest: The name of the attribute to be added to the object returned by parse_args().
+            const: covered by type-hint and default value given
+            choices: covered by enum type
+
+            action: The basic type of action to be taken when this argument is encountered at the command line.
         :type action: Union[str, Type[argparse.Action]]
         """
         name = kwargs.pop('name', None)

arger/parser/funcs.py

@@ -43,34 +43,7 @@ def create_option(param: Param, default, option_generator):
 
 
 def prepare_arguments(func, param_docs) -> Dict[str, Option]:
-    """Parse 'func' and adds parser arguments from function signature.
-
-    :param func: Function's signature is used to create parser
-        * positional_params:
-            Positional arguments become mandatory.
-        * kw_params:
-            All keyword arguments in the function definition are options.
-            Arbitrary args and values can be captured with **kwargs
-        * annotations:
-            used to determine the type and action of the arguments
-            list, tuple, Enum are supported, List[Enum] are supported
-    :param param_docs:
-        * The top part of the docstring becomes the usage message for the app.
-
-        * Below that, ReST-style :param: lines in the following format describe the option
-
-        * Options are further defined in the docstring.
-            * the format is
-            .. highlight::
-                :param name: [short option and/or long option] help text
-                :param variable_name: -v --verbose the help_text for the variable
-                :param variable_name: -v the help_text no long option
-                :param variable_name: --verbose the help_text no short option
-
-            * variable_name is the name of the variable in the function specification and
-        must refer to a keyword argument. All options must have a :param: line like
-        this.
-    """
+    """Parse 'func' and adds parser arguments from function signature."""
     positional_params, kw_params = prepare_params(func, param_docs)
     option_generator = generate_options()
     next(option_generator)

docs/arger.md

@@ -0,0 +1,33 @@
+# API
+A command/sub-command is parsed from function.
+
+## Function
+Function's signature is used to create parser
+
+### 1. Positional Arguments:
+Positional arguments become mandatory.
+
+### 2. Keyword Arguments:
+All keyword arguments in the function definition are options.
+Arbitrary args and values can be captured with **kwargs
+
+### 3. type annotations:
+used to determine the type and action of the arguments
+list, tuple, Enum are supported, List[Enum] are supported
+
+### 4. Docstring (ReST or GoogleDoc)
+- The top part of the docstring becomes the usage message for the app.
+- ReST or GoogleDoc-style :param: lines in the following format describe the option
+- Options-strings can further be defined in the docstring.  
+```pydocstring
+Args:
+    name: [short option and/or long option] help text
+    variable_name: -v --verbose the help_text for the variable
+    variable_name: -v the help_text no long option
+    variable_name: --verbose the help_text no short option
+```
+
+::: arger.parser.classes.Option
+::: arger.parser.classes.Argument
+::: arger.Arger
+

tests/examples/1_single_function.md → docs/examples/1_single_function.md

@@ -1,23 +1,30 @@
-# Usages
-1. ran with both options
-```shell script
-$ python 1_single_function.py 10 p2
+# Single Command
+in a file named `main.py`
+
+```python
+--8<-- "single_function.py"
+```
+
+## ran with both positional arguments
+
+```sh
+$ python single_function.py 10 p2
 kw1 (<class 'NoneType'>): None
 kw2 (<class 'bool'>): False
 param1 (<class 'int'>): 10
 param2 (<class 'str'>): p2
 ```
 
-1. ran empty
-```shell script
-$ python 1_single_function.py
+##  ran empty
+```sh
+$ python single_function.py
 usage: pytest [-h] [-k KW1] [-w] param1 param2
 pytest: error: the following arguments are required: param1, param2
 ```
 
-2. ran help
-```shell script
-$ python 1_single_function.py --help
+## ran help
+```sh
+$ python single_function.py --help
 usage: pytest [-h] [-k KW1] [-w] param1 param2
 
 Example function with types documented in the docstring.
@@ -32,23 +39,23 @@ optional arguments:
   -w, --kw2
 ```
 
-3. ran with invalid option
-```shell script
-$ python 1_single_function.py --invalid
+## ran with invalid option
+```sh
+$ python single_function.py --invalid
 usage: pytest [-h] [-k KW1] [-w] param1 param2
 pytest: error: the following arguments are required: param1, param2
 ```
 
-4. ran with invalid type
-```shell script
-$ python 1_single_function.py p1 p2
+## ran with invalid type
+```sh
+$ python single_function.py p1 p2
 usage: pytest [-h] [-k KW1] [-w] param1 param2
 pytest: error: argument param1: invalid int value: 'p1'
 ```
 
-5. ran with one argument missing
-```shell script
-$ python 1_single_function.py p1
+## ran with one argument missing
+```sh
+$ python single_function.py p1
 usage: pytest [-h] [-k KW1] [-w] param1 param2
 pytest: error: argument param1: invalid int value: 'p1'
 ```