Merge pull request #2 from landoskape/dev

Documentation improvements for 0.1.3

conditional_parser.py

@@ -4,7 +4,7 @@
 from inspect import signature
 from argparse import ArgumentParser, Namespace
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 
 class ConditionalArgumentParser(ArgumentParser):

docs/source/api.rst

@@ -0,0 +1,37 @@
+API Reference
+=============
+
+ConditionalArgumentParser
+-------------------------
+
+.. autoclass:: conditional_parser.ConditionalArgumentParser
+   :show-inheritance:
+   :special-members: __init__
+   :members: add_conditional, parse_args
+
+
+The ConditionalArgumentParser extends Python's ArgumentParser to support conditional
+arguments. It inherits all standard ArgumentParser functionality while adding the ability
+to specify arguments that only appear when certain conditions are met.
+
+Key Methods
+-----------
+
+The main addition to ArgumentParser is the :meth:`add_conditional` method, which allows you to add a conditional argument to the parser. This method takes the same arguments as the standard :meth:`add_argument` method, with the addition of a `dest` and `cond` arguments which specify the destination in the namespace to check for the condition and the condition itself, respectively. 
+
+.. note::
+   The ``dest`` argument is the name of the argument in the namespace that will be checked for the condition. The nomenclature might be a bit confusing; it's used to be consistent with how the ``ArgumentParser`` assigns arguments to the namespace. 
+
+   What you are looking for is whatever attribute name you'd use to get the value of the argument from the output of ``parse_args()``. So, for example:
+
+   .. code-block:: python
+        
+        from argparse import ArgumentParser
+        parser = ArgumentParser()
+        parser.add_argument("--use-regularization", default=False, action="store_true")
+        parser.add_argument("--nohyphen", default=False, action="store_true")
+        args = parser.parse_args(["--use-regularization"])
+        # The "dest" of --use-regularization is "use_regularization"
+        print(args.use_regularization) # True
+        # The "dest" of --nohyphen is "nohyphen"
+        print(args.nohyphen) # False

docs/source/conf.py

@@ -13,7 +13,7 @@
 project = "Conditional Parser"
 copyright = "2024, Andrew T. Landau"
 author = "Andrew T. Landau"
-release = "0.1.2"
+release = "0.1.3"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/source/index.rst

@@ -1,26 +1,21 @@
 Conditional Parser
-=================
+==================
 
-A flexible extension to Python's ArgumentParser for conditional arguments.
+A flexible extension to Python's ``ArgumentParser`` that enables dynamic, conditional command-line arguments - arguments that only appear based on the values of other arguments.
+
+The argparse module is fantastic, but it lacks the ability to flexibly create conditional arguments. While the native ``ArgumentParser`` supports the ability to make a single subcommand, it does not have the ability to make multiple conditional arguments in parallel, in hierarchical structures, or with complex conditional logic. The ``ConditionalArgumentParser`` extends the native ``ArgumentParser`` to support these features while maintaining the familiar interface.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
    installation
    quickstart
    examples/index
-   api/index
-
-About
------
-
-The Conditional Parser package extends Python's native ArgumentParser to enable dynamic, 
-conditional command-line arguments - arguments that only appear based on the values of 
-other arguments.
+   api
 
 Key Features
------------
+------------
 
 * Seamless extension of Python's ArgumentParser
 * Support for conditional arguments based on other argument values
@@ -29,7 +24,9 @@ Key Features
 * Compatible with existing ArgumentParser usage
 
 Quick Example
-------------
+-------------
+
+Suppose your parser includes a ``--use-regularization`` flag for training a machine learning model. When this flag is used, you'd probably want to include another argument ``--regularizer-lambda`` to control the regularization strength - but this parameter is only relevant when regularization is enabled. With ``ConditionalArgumentParser``, you can easily add this conditional argument.
 
 .. code-block:: python
 
@@ -38,10 +35,12 @@ Quick Example
     parser = ConditionalArgumentParser()
     parser.add_argument("--use-regularization", action="store_true")
     
-    # Will only add if --use-regularization is used, e.g. if use_regularization is set to True
+    # Will only add if --use-regularization is used
+    # E.g. if args.use_regularization == True
     parser.add_conditional(
-        "use_regularization", True,
-        "--regularizer-lambda", 
+        "use_regularization", True, # parent / condition
+        "--regularizer-lambda", # conditional argument
+        # parameters for the conditional argument - these are totally normal!
         type=float, 
         default=0.01
     )

docs/source/installation.rst

@@ -1,5 +1,5 @@
 Installation
-===========
+============
 
 The package is available on PyPI and can be installed using pip:
 
@@ -8,12 +8,12 @@ The package is available on PyPI and can be installed using pip:
     pip install conditional-parser
 
 Requirements
------------
+------------
 
 Conditional Parser has no external dependencies beyond Python's standard library.
 
 Development Installation
-----------------------
+------------------------
 
 To install for development:
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "conditional-parser"
-version = "0.1.2"
+version = "0.1.3"
 authors = [
     {name = "Andrew Landau", email = "[email protected]"},
 ]