Updates to docs

- more links to numpydoc guide
- clarifies dependencies to build docs

docs/api/index.rst

@@ -69,3 +69,4 @@ For those of you who want the gritty details.
     :maxdepth: 1
 
     mplhooks
+

docs/devguide.rst

@@ -51,7 +51,7 @@ is open to interpretation.
   ``"""triple double quotes"""`` for docstrings. Double quotes are allowed to
   prevent single quote escaping, e.g. ``"Y'all c'mon o'er here!"``
 * We use sphinx with the numpydoc extension to autogenerate API documentation. Follow
-  the numpydoc standard for docstrings `described here <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
+  the `numpydoc`_ standard for docstrings.
 * Simple functions should have simple docstrings.
 * Lines should be at most 80 characters long. The 72 and 79 character
   recommendations from PEP8 are not required here.
@@ -112,7 +112,7 @@ include the unit test module. This will execute any unit tests that are
 part of the change as well as the unit tests for xonsh source modules in
 the change::
 
-    $ scripts/run_tests.xsh 
+    $ scripts/run_tests.xsh
 
 If you want to run specific tests you can specify the test names to
 execute. For example to run test_aliases::
@@ -148,7 +148,7 @@ Docstrings
 No matter what language you are writing in, you should always have
 documentation strings along with you code. This is so important that it is
 part of the style guide.  When writing in Python, your docstrings should be
-in reStructured Text using the numpydoc format.
+in reStructured Text using the `numpydoc`_ format.
 
 ------------------------
 Auto-Documentation Hooks
@@ -346,4 +346,5 @@ Document History
 Portions of this page have been forked from the PyNE documentation,
 Copyright 2011-2015, the PyNE Development Team. All rights reserved.
 
-.. _PEP8: http://www.python.org/dev/peps/pep-0008/
+.. _PEP8: https://www.python.org/dev/peps/pep-0008/
+.. _numpydoc: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

requirements-docs.txt

@@ -0,0 +1,3 @@
+cloud_sptheme
+numpydoc==0.5
+Sphinx

xonsh/environ.py

@@ -353,9 +353,9 @@ DEFAULT_DOCS = {
         'Whether or not to suppress directory stack manipulation output.'),
     'RAISE_SUBPROC_ERROR': VarDocs(
         'Whether or not to raise an error if a subprocess (captured or '
-        'uncaptured) returns a non-zero exit status, which indicates failure.'
+        'uncaptured) returns a non-zero exit status, which indicates failure. '
         'This is most useful in xonsh scripts or modules where failures '
-        'should cause an end to execution. This is less useful at a terminal.'
+        'should cause an end to execution. This is less useful at a terminal. '
         'The error that is raised is a subprocess.CalledProcessError.'),
     'RIGHT_PROMPT': VarDocs('Template string for right-aligned text '
         'at the prompt. This may be parameterized in the same way as '
@@ -726,7 +726,7 @@ def _is_executable_file(path):
 def yield_executables_windows(directory, name):
     normalized_name = os.path.normcase(name)
     extensions = builtins.__xonsh_env__.get('PATHEXT')
-    try: 
+    try:
         names = os.listdir(directory)
     except PermissionError:
         return
@@ -741,10 +741,10 @@ def yield_executables_windows(directory, name):
 
 
 def yield_executables_posix(directory, name):
-    try: 
+    try:
         names = os.listdir(directory)
     except PermissionError:
-        return 
+        return
     if name in os.listdir(directory):
         path = os.path.join(directory, name)
         if _is_executable_file(path):