Advanced usage
==============

Preventing `sphinxcontrib-argdoc` from processing one or more, but not all scripts, in a package
------------------------------------------------------------------------------------------------
To prevent :obj:`sphinxcontrib.argdoc` from processing a :term:`main-like function`,
in one of the :term:`executable scripts` in your package, use the
:func:`~sphinxcontrib.argdoc.ext.noargdoc` function decorator. For example::

    #!/usr/bin/env python
    import argparse
    from sphinxcontrib.argdoc import noargdoc

    @noargdoc
    def main():
        """Main-like function that would normally be processed by
        `sphinxcontrib-argdoc` but that will instead be skipped!
        """
        # main function body here
        parser = argparse.ArgumentParser()
        pass

    if __name__ == "__main__":
        main()


.. _other-main-name: 

Processing a :term:`main-like function` named something other than `main`
-------------------------------------------------------------------------
If your code conventions use a name different from `main` for
:term:`main-like functions <main-like function>`, :data:`sphinxcontrib.argdoc`
can still process these. Just set the value of the configuration
parameter `argdoc_main_func` to your function name in ``conf.py``::

    ...

    # somewhere in conf.py
    argdoc_main_func = "whatever_we_call_main_funcs_at_our_organization"

    ...


.. _alt-prefix-chars:

Using alternate prefix characters in your :class:`~argparse.ArgumentParser`
---------------------------------------------------------------------------
If your :term:`executable script <executable scripts>` uses one or more 
alternate `prefix characters`_ (e.g. `'+'` instead of or in addition to `'-'`,
set the configuration parameter `argdoc_prefix_chars` to a string
containing all of the prefix characters used by all of your scripts in 
your ``conf.py``::

    # somewhere in conf.py
    argdoc_prefix_chars = "-+" # our scripts use both '-' and '+' to prefix optional arguments


Debugging :data:`sphinxcontrib.argdoc` output
---------------------------------------------
To save a snapshot of the raw `reStructuredText`_ generated by :data:`argdoc`
for each file after processing, set `argdoc_save_rst` to `True` in your
``conf.py``. In your ``build`` folder, you will find files names
``X_postargdoc.rst`` where `X` corresponds to the name of the ``rst`` stub
file.
