From 05bad9af2a47caccc86459960239409a7fe2f557 Mon Sep 17 00:00:00 2001 From: Frank Sachsenheim Date: Sun, 15 May 2016 12:55:38 +0200 Subject: [PATCH] Updates to docs - more links to numpydoc guide - clarifies dependencies to build docs --- docs/api/index.rst | 1 + docs/devguide.rst | 9 +++++---- requirements-docs.txt | 3 +++ xonsh/environ.py | 10 +++++----- 4 files changed, 14 insertions(+), 9 deletions(-) create mode 100644 requirements-docs.txt diff --git a/docs/api/index.rst b/docs/api/index.rst index 2784c59e4..3762c5c9d 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -69,3 +69,4 @@ For those of you who want the gritty details. :maxdepth: 1 mplhooks + diff --git a/docs/devguide.rst b/docs/devguide.rst index 5c47843be..eb830c57d 100644 --- a/docs/devguide.rst +++ b/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 `_. + 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 diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 000000000..c465e0f51 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,3 @@ +cloud_sptheme +numpydoc==0.5 +Sphinx diff --git a/xonsh/environ.py b/xonsh/environ.py index 0e27dd4b5..bdf11f4ab 100644 --- a/xonsh/environ.py +++ b/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):