Initial release

Signed-off-by: Stephen Finucane <stephen@that.guru>

README.rst

@@ -7,3 +7,46 @@ documentation from a `click-based`__ application and include it in your docs.
 
 __ http://www.sphinx-doc.org/
 __ http://click.pocoo.org/
+
+Installation
+------------
+
+Install the plugin using `pip`:
+
+.. code-block:: shell
+
+   $ pip install sphinx-click
+
+Alternatively, install from source by cloning this repo then running
+`setup.py`:
+
+.. code-block:: shell
+
+   $ python setup.py install
+
+Usage
+-----
+
+.. important::
+
+   To document a click-based application, both the application itself and any
+   additional dependencies required by that application **must be installed**.
+
+Enable the plugin in your Sphinx `conf.py` file:
+
+.. code-block:: python
+
+   extensions = ['sphinx_click.ext']
+
+Once enabled, you can now use the plugin wherever necessary in the
+documentation.
+
+.. code-block::
+
+   .. click::
+      :module: my_path.to.my_module
+      :func: my_func
+      :prog: hello-world
+
+Detailed information on the various options available is provided in the
+`documentation <https://sphinx-click.readthedocs.io>`_.

docs/changelog.rst

@@ -0,0 +1,5 @@
+Changes
+=======
+
+.. include:: ../ChangeLog
+   :start-line: 2

docs/contributing.rst

@@ -0,0 +1,57 @@
+Contribution
+============
+
+We welcome all contributions to `sphinx-click`.
+
+Support
+-------
+
+Open and issue in the `issue tracker`_ for all support requests.
+`StackOverflow`_ is also worth considering.
+
+Reporting Issues
+----------------
+
+Report all issues in the `issue tracker`_. When doing so, please include
+version information for:
+
+- Python
+- `click`
+- `sphinx-click`
+
+Submitting Patches
+------------------
+
+All patches should be submitted as pull requests on the `GitHub project`_.
+
+- Include tests if fixing a bug
+
+- Clearly explain what you're trying to accomplish
+
+- Follow :pep:`8`. You can use the `pep8` tox target for this
+
+Testing
+-------
+
+`sphinx-click` uses `tox` and `unittest` for testing. To run all tests, run:
+
+.. code-block:: shell
+
+    $ tox
+
+We support a number of Python versions. To list available environments, run:
+
+.. code-block:: shell
+
+    $ tox --list
+
+To run one of these environments, such as `py27` which runs tests under Python
+2.7, run:
+
+.. code-block:: shell
+
+    $ tox -e py27
+
+.. _issue tracker: https://github.com/click-contrib/sphinx-click/issues
+.. _StackOverflow: https://stackoverflow.com
+.. _GitHub project: https://github.com/click-contrib/sphinx-click

docs/index.rst

@@ -1,15 +1,26 @@
-Welcome to sphinx-click's documentation!
-========================================
+sphinx-click
+============
+
+:mod:`sphinx-click <sphinx_click>` is a `Sphinx`__ plugin that allows you to
+automatically extract documentation from a `click-based`__ application and
+include it in your docs.
+
+__ http://www.sphinx-doc.org/
+__ http://click.pocoo.org/
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
+   installation
+   usage
+   contributing
+   changelog
 
+.. seealso::
 
-Indices and tables
-==================
+    Module :mod:`click`
+      This extension assumes you are using :mod:`click` to create your command
+      line application.
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+    Module :mod:`sphinxcontrib.autoprogram`
+      An equivalent library for use with :mod:`argparse`.

docs/installation.rst

@@ -0,0 +1,20 @@
+Installation
+============
+
+Install the plugin using `pip`:
+
+.. code-block:: shell
+
+   $ pip install sphinx-click
+
+Alternatively, install from source by cloning this repo then running
+`setup.py`:
+
+.. code-block:: shell
+
+   $ python setup.py install
+
+.. important::
+
+   Both the package you're referencing and any dependencies **must be
+   installed**.

docs/usage.rst

@@ -0,0 +1,71 @@
+Usage
+=====
+
+`sphinx-click` enables automatic documentation by way of a `Sphinx
+directive`__.
+
+.. rst:directive:: .. click:: module:parser
+
+   Automatically extract documentation from a `click-based`__ application and
+   include it in your docs.
+
+   .. code-block:: rst
+
+       .. click:: module:parser
+          :prog: hello-world
+          :show-nested:
+
+   The directive takes the import name of the parser object as its sole
+   argument.
+
+   In addition, the following options are required:
+
+   `:prog:`
+     The name of your tool (or how it should appear in your documentation). For
+     example, if you run your script as ``./boo --opts args`` then ``:prog:``
+     will be ``boo``. If this is not given, the module name is used.
+
+   The following options are optional:
+
+   `:show-nested:`
+     Enable full documentation for sub-commands.
+
+__ http://www.sphinx-doc.org/en/stable/extdev/markupapi.html
+__ http://click.pocoo.org/
+
+Example
+-------
+
+Take the below `click` application, which is defined in the `example_app`
+module:
+
+.. code-block:: python
+
+    import click
+
+    @click.group()
+    def greet():
+        """A sample command group."""
+        pass
+
+    @greet.command()
+    @click.argument('user')
+    def hello(user):
+        """Greet a user."""
+        click.echo('Hello %s' % user)
+
+To document this, use the following:
+
+.. code-block:: rst
+
+    .. click:: hello_world:greet
+      :prog: hello-world
+
+If you wish to include full documentation for the subcommand, ``hello``, in the
+output, add the ``show-nested`` flag.
+
+.. code-block:: rst
+
+    .. click:: hello_world:greet
+      :prog: hello-world
+      :show-nested:

setup.cfg

@@ -7,7 +7,7 @@ classifiers =
     Programming Language :: Python :: 2
     Programming Language :: Python :: 3
     Programming Language :: Python
-    Development Status :: 1 - Planning
+    Development Status :: 5 - Production/Stable
     Environment :: Console
     Intended Audience :: Developers
     Intended Audience :: Information Technology
@@ -28,6 +28,7 @@ all-files = 1
 warning-is-error = 1
 build-dir = docs/_build
 source-dir = docs
+builders = html
 
 [wheel]
 universal = 1