.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "auto_examples/plot_e03_docstrings.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_auto_examples_plot_e03_docstrings.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_auto_examples_plot_e03_docstrings.py:


Doc Strings
===========
In addition to parsing function signatures, the module assumes
that your functions are documented with doc strings according to  the
|numpy style guide|_.

This tutorial goes over how to use the doc-strings to further customize
your CLI.

.. GENERATED FROM PYTHON SOURCE LINES 11-14

.. code-block:: Python


    from npdoc_cli import cli








.. GENERATED FROM PYTHON SOURCE LINES 15-20

Summary
-------
The ``Summary`` and  ``Extended Summary`` of the doc string are converted into the
help message of your parser. The descriptions in the ``Parameters`` section
are converted into the help message for each argument

.. GENERATED FROM PYTHON SOURCE LINES 20-41

.. code-block:: Python


    cli.reset()
    @cli.program
    def hello(name: str, number: int):
        """
        This is a summary line.

        This is an extended summary line.

        Parameters
        ----------
        name : str
            This is a help message.
        """
        for i in range(number):
            print('hello', name)


    cli.build()
    cli.print_help()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    usage: hello [-h] name

    This is a summary line. This is an extended summary line.

    positional arguments:
      name        This is a help message.

    options:
      -h, --help  show this help message and exit




.. GENERATED FROM PYTHON SOURCE LINES 42-52

Choices
-------
Sometimes a function expects specific choices.
You can include those in the ``Parameters`` section, and they will be 
added to the parser, which will check that a valid choice was passed
as a command line argument.

To do this, add a curly braces next to the doc strings type indication
formatted as ``{val2, val2, ...}`` where the first value is the default.
Each item in the choices will be cast into the type in the signature.

.. GENERATED FROM PYTHON SOURCE LINES 52-70

.. code-block:: Python


    cli.reset()
    @cli.program
    def options(o: str = 'a'):
        """
        Parameters
        ----------
        o : str, {a, b, c}
            This function expects a, b, or c.
        """
        print(o)

    cli.build()
    try:
        args = cli.parse_args(['-o', 'd'])
    except SystemExit as e:
        print(e)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    usage: options [-h] [-o {a,b,c}]
    options: error: argument -o/--o: invalid choice: 'd' (choose from 'a', 'b', 'c')
    2




.. GENERATED FROM PYTHON SOURCE LINES 71-84

Action, Nargs, and Required
---------------------------
Underhood the hood, the module is generating an |argparse argument|_ and
some settings
don't fit nicely into the signature or |numpy style guide|_. For those,
you can include them in the descriptions of the argument in the ``Parameters``
section.

These settings should be formatted as: 
``For CLI argument key = <val>, ...`` and ended with a period. The spaces and
period are important and must be included properly on a single line.

This line will not be included in the help message of the generated CLI.

.. GENERATED FROM PYTHON SOURCE LINES 84-99

.. code-block:: Python


    cli.reset()
    @cli.program
    def options(mylist: list[str] = []):
        """
        Parameters
        ----------
        mylist : list[str]
            This function expects some strings.
            For CLI argument required = True, action = append, nargs = *.
        """
        print(mylist)

    cli.build()
    cli.print_help()




.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    usage: options [-h] -m [MYLIST ...]

    options:
      -h, --help            show this help message and exit
      -m [MYLIST ...], --mylist [MYLIST ...]
                            This function expects some strings.





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.003 seconds)


.. _sphx_glr_download_auto_examples_plot_e03_docstrings.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_e03_docstrings.ipynb <plot_e03_docstrings.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_e03_docstrings.py <plot_e03_docstrings.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_e03_docstrings.zip <plot_e03_docstrings.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_