Start on docs (using Sphinx)

README.rst

@@ -33,51 +33,6 @@ License
 
 MIT
 
-Defining Commands
-=================
-
-::
-
-    from runcommands import command
-
-    @command
-    def hello(config, name=None):
-        if name:
-            print('Hello,', name)
-        else:
-            print('Hello, World')
-
-Listing Commands
-================
-
-::
-
-    > runcommands --list
-    RunCommands 1.0
-
-    Available commands:
-
-        hello
-
-    For detailed help on a command: run <command> --help
-
-    > runcommands hello --help
-    usage: hello [-h] [-n NAME]
-
-    optional arguments:
-      -h, --help            show this help message and exit
-      -n NAME, --name NAME
-
-Running Commands
-================
-
-::
-
-    > runcommands hello
-    Hello, World
-    > runcommands hello -n You
-    Hello, You
-
 Built in Commands
 =================
 

commands.py

@@ -318,6 +318,16 @@ def update_line(file_name, line_number, content):
         local(config, ('git commit', init_module, changelog, msg))
 
 
+@command
+def build_docs(config, source='docs', destination='docs/_build', type_='html'):
+    local(config, (
+        'sphinx-build',
+        '-b', type_,
+        source,
+        destination,
+    ))
+
+
 if __name__ == '__main__':
     from runcommands.__main__ import main
     sys.exit(main())

docs/conf.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+import os
+import sys
+from datetime import date
+
+sys.path.insert(0, os.path.abspath('..'))
+
+from runcommands import __version__
+
+# -- General configuration ------------------------------------------------
+
+project = 'RunCommands'
+author = 'Wyatt Baldwin'
+copyright = '{year} Wyatt Baldwin'.format(year=date.today().year)
+
+version = __version__
+release = version
+
+language = None
+
+master_doc = 'index'
+
+source_suffix = '.rst'
+
+templates_path = ['_templates']
+
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+pygments_style = 'sphinx'
+
+todo_include_todos = False
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.viewcode',
+]
+
+# reStructuredText options ------------------------------------------------
+
+# This makes `xyz` the same as ``xyz``.
+default_role = 'literal'
+
+# This is appended to the bottom of all docs.
+rst_epilog = """
+.. |project| replace:: {project}
+.. |github_url| replace:: https://github.com/wylee/runcommands
+""".format_map(locals())
+
+# Options for autodoc extension -------------------------------------------
+
+autodoc_default_flags = ['members']
+
+# Options for intersphinx extension ---------------------------------------
+
+intersphinx_mapping = {
+    'python': ('http://docs.python.org/3.3', None),
+}
+
+# -- Options for HTML output ----------------------------------------------
+
+html_theme = 'alabaster'
+
+html_theme_options = {
+    'description': 'Easily define and run multiple commands',
+    'github_user': 'wylee',
+    'github_repo': 'runcommands',
+    'page_width': '940px',
+    'fixed_sidebar': True,
+    'sidebar_width': '300px',
+}
+
+html_sidebars = {
+    '**': [
+        'about.html',
+        'navigation.html',
+        'searchbox.html',
+    ]
+}
+
+html_static_path = []
+
+# -- Options for HTMLHelp output ------------------------------------------
+
+htmlhelp_basename = 'RunCommandsdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {}
+
+latex_documents = [
+    (master_doc, 'RunCommands.tex', 'RunCommands Documentation', 'Wyatt Baldwin', 'manual'),
+]
+
+# -- Options for manual page output ---------------------------------------
+
+man_pages = [
+    (master_doc, 'runcommands', 'RunCommands Documentation', [author], 1)
+]
+
+# -- Options for Texinfo output -------------------------------------------
+
+texinfo_documents = [
+    (master_doc, 'RunCommands', 'RunCommands Documentation', author, 'RunCommands',
+     'One line description of project.', 'Miscellaneous'),
+]

docs/defining-commands.rst

@@ -0,0 +1,50 @@
+Defining Commands
++++++++++++++++++
+
+Commands are defined like so:
+
+.. code-block:: python
+
+    from runcommands import command
+
+    # Pull in some pre-defined commands
+    from runcommands.commands import local, show_config
+
+    @command
+    def hello(config, name=None):
+        """Greet someone (or the whole world)."""
+        if name:
+            print('Hello,', name)
+        else:
+            print('Hello, World')
+
+Listing Commands
+================
+
+Once some commands are defined (and/or imported), they can be listed on
+the command line like this::
+
+    > runcommands -l
+    RunCommands 1.0a15.dev0
+
+    Available commands:
+
+        hello local show-config
+
+    For detailed help on a command: runcommands <command> --help
+
+Showing a Command's Help/Usage
+==============================
+
+Help for a command can be shown like this::
+
+    > runcommands hello --help
+    usage: hello [-h] [-n NAME]
+
+    Greet someone (or the whole world)
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -n NAME, --name NAME
+
+Note that the `hello` command's docstring is shown too.

docs/index.rst

@@ -0,0 +1,48 @@
+RunCommands Documentation
++++++++++++++++++++++++++
+
+|project| is a simple, Python 3-only command runner that automatically
+generates `argparse`-style console scripts from function definitions.
+
+A basic run looks like this::
+
+    > run --env production build-static deploy --version 1.0
+
+In this example, two commands, `build-static` and `deploy`, are being
+run with the production environment's configuration.
+
+One nice thing about using `argparse` behind the scenes is that help
+is built in::
+
+    > run deploy --help
+    usage: deploy [-h] [-v VERSION] ...
+
+    Deploy a new version
+
+Quick Start
+===========
+
+Check out the :doc:`quick-start` to get up and running.
+
+Links
+=====
+
+* `Source Code (GitHub) <https://github.com/wylee/runcommands>`_
+
+Contents
+========
+
+.. toctree::
+    :maxdepth: 2
+
+    installation
+    quick-start
+    defining-commands
+    running-commands
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.rst

@@ -0,0 +1,21 @@
+Installation
+++++++++++++
+
+|project| can be installed from PyPI in the usual ways:
+
+- `pip install runcommands`
+- Add `runcommands` to `install_requires` in the project's `setup.py`
+- Add `runcommands` to the project's Pip requirements file
+
+The latest in-development version can be installed from GitHub::
+
+    pip install |github_url|
+
+Development
+===========
+
+To install the project for development::
+
+    git clone |github_url|
+    cd runcommands
+    ./commands.py install

docs/quick-start.rst

@@ -0,0 +1,2 @@
+Quick Start
++++++++++++

docs/running-commands.rst

@@ -0,0 +1,2 @@
+Running Commands
+++++++++++++++++

setup.py

@@ -33,6 +33,7 @@
         'dev': [
             'coverage',
             'flake8',
+            'Sphinx',
         ],
         'paramiko': [
             'paramiko>=2.1.2',