Start on docs (using Sphinx)

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,108 @@
+#!/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}
+""".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,2 @@
+Defining Commands
++++++++++++++++++

docs/index.rst

@@ -0,0 +1,43 @@
+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
+
+In this example, two commands, `build-static` and `deploy`, are being
+run with the production environment's configuration.
+
+Here's another example::
+
+    run release --version 1.0 upload
+
+First, release 1.0 is created and then it's uploaded to PyPI.
+
+Check out the :doc:`quick-start` to get up and running.
+
+Links
+=====
+
+* `Source Code (GitHub) <https://github.com/wylee/runcommands>`_
+
+Contents
+========
+
+.. toctree::
+    :maxdepth: 2
+
+    quick-start
+    installation
+    defining-commands
+    running-commands
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/installation.rst

@@ -0,0 +1,8 @@
+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

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',