Addressed some of comments in #153

.gitignore

@@ -1,11 +1,11 @@
 .ipynb_checkpoints/
-docs/_build/
-docs/rst-tutorials/
+build/
+tutorials/rst-tutorials/
 IPython-*
 *.fits
 *.pdf
 *.png
 *.jpg
 *.pyc
 *.tex
-exec*.ipynb
+exec*.ipynb

.rtd-environment.yml

@@ -14,4 +14,4 @@ dependencies:
   - jupyter=1.0
   - notebook=5.0
   - pip:
-    - git+https://github.com/jupyter/nbconvert
+    - git+https://github.com/jupyter/nbconvert # this is really >=5.4, but at the time of adding this that wasn't yet available

README.rst

@@ -23,3 +23,14 @@ The tutorials are initially empty of any output.  You can run them by pressing
 
 See the conda environment file or pip requirements file for a list of
 dependencies.
+
+## Building the tutorial web pages
+
+To build all of the tutorials in the form they appear on the web site, you just
+do the sphinx build as for a Python package::
+
+  >>> python setup.py build_docs
+
+For more information on this and other ways to execute the tutorials, see the
+"Documentation on tutorials infrastructure" section of the generated
+sphinx docs.

scripts/check_env.py

@@ -39,52 +39,31 @@
 
 from astropy import log as logger
 
-def check_environment(tutorial=None):
+def check_environment(tutorials_base_path, tutorial=None):
     error = False
     warnings = False
     # 'enter' checks if the tutorial name passed by user exists in the repository
     enter = False
     logger.info("Running Environment Tests...")
-    _orig_path = os.getcwd()
-    tutorials_base = os.path.join(_orig_path, 'tutorials')
-    for tutorial_name in os.listdir(tutorials_base):
+    for tutorial_name in os.listdir(tutorials_base_path):
+        print(tutorial_name,'ARG')
         if (tutorial_name == tutorial or tutorial is None):
             enter = True
-            tutorial_path = os.path.join(
-                tutorials_base,
-                tutorial_name)  # Path to tutorial folder
+            tutorialreq_path = os.path.join(tutorials_base_path, tutorial_name,
+                                            'requirements.txt')  # Path to tutorial folder
             try:
-                with open(tutorial_path + "/requirements.json") as data_file:
-                    # Import data from json file
-                    data = json.load(data_file)
+                with open(tutorialreq_path) as req_file:
                     # Check for all the packages to be imported
-                    for pkgname in data:
-                        # Check for versioning
-                        for subinfo in data[pkgname]:
-                            if subinfo == 'min_version':
-                                if(not astropy.utils.introspection.minversion(pkgname, data[pkgname][subinfo])):
-                                    logger.error(
-                                        "Package " +
-                                        pkgname +
-                                        " is either missing or is out of date to run Tutorial: " +
-                                        tutorial_name)
-                                    error = True
-                                    #Package is Missing
-                            elif subinfo == 'pref_version':
-                                if(not astropy.utils.introspection.minversion(pkgname, data[pkgname][subinfo])):
-                                    logger.warning(
-                                        "Please upgrade Package " +
-                                        pkgname +
-                                        " to version " +
-                                        data[pkgname][subinfo] +
-                                        " for Tutorial: " +
-                                        tutorial_name)
-                                    warnings = True
-                                    # Out of date package is present
+                    for line in req_file:
+                        line_strip = line.strip()
+                        astropy.utils.introspection.minversion(line_strip, '')
+                logger.info('Sucessfully checked requirements for '
+                            '"{}".'.format(tutorial_name))
+
             except IOError:
-                error = True
-                logger.error(
-                    "Environment Check Failed ! requirements.json not found")
+                warnings = True
+                logger.warn('requirements.txt not found for "{}" - couldn\'t do'
+                            ' environment check.'.format(tutorial_name))
 
     if not enter:
         logger.error(
@@ -112,6 +91,10 @@ def check_environment(tutorial=None):
                         help="A regular expression to select the names of the "
                              "notebooks to be processed.  If not given, all "
                              "notebooks will be used.")
+    parser.add_argument("tutorial_base_path", default='tutorials/notebooks',
+                        nargs='?',
+                        help="The path to the root of the tutorial "
+                             "directories.")
 
     args = parser.parse_args()
-    check_environment(args.nameregex)  # name passed to check_env function
+    check_environment(args.tutorial_base_path, args.nameregex)  # name passed to check_env function

scripts/convert.py

@@ -15,7 +15,7 @@
 class NBConverter(object):
 
     def __init__(self, nb_path, output_path=None, template_file=None,
-                 overwrite=False):
+                 overwrite=False, kernel_name=None):
         self.nb_path = path.abspath(nb_path)
         fn = path.basename(self.nb_path)
         self.path_only = path.dirname(self.nb_path)
@@ -41,6 +41,11 @@ def __init__(self, nb_path, output_path=None, template_file=None,
         logger.info('Processing notebook {0} (in {1})'.format(fn,
                                                               self.path_only))
 
+        if kernel_name is None:
+            self.kernel_name = ExecutePreprocessor.kernel_name.default_value
+        else:
+            self.kernel_name = kernel_name
+
     def execute(self, write=True):
         """
         Execute the specified notebook file, and optionally write out the
@@ -66,8 +71,11 @@ def execute(self, write=True):
             return self._executed_nb_path
 
         # Execute the notebook
-        logger.debug('Executing notebook...')
-        executor = ExecutePreprocessor(timeout=900, kernel_name='python3')
+        logger.debug('Executing notebook using kernel '
+                     '"{}"...'.format(self.kernel_name))
+        executor = ExecutePreprocessor(timeout=900,
+                                       kernel_name=self.kernel_name)
+
         with open(self.nb_path) as f:
             nb = nbformat.read(f, as_version=IPYTHON_VERSION)
 
@@ -197,7 +205,8 @@ def process_notebooks(nbfile_or_path, exec_only=False, **kwargs):
                         help='Re-run and overwrite any existing executed '
                              'notebook or RST files.')
 
-    parser.add_argument('nbfile_or_path', default=None,
+    parser.add_argument('nbfile_or_path', default='tutorials/notebooks/',
+                        nargs='?',
                         help='Path to a specific notebook file, or the '
                              'top-level path to a directory containing '
                              'notebook files to process.')
@@ -212,6 +221,11 @@ def process_notebooks(nbfile_or_path, exec_only=False, **kwargs):
                              'converted files will be in the same path as the '
                              'source notebooks.')
 
+    parser.add_argument('--kernel-name', default='python3', dest='kernel_name',
+                        help='The name of the kernel to run the notebooks with.'
+                             ' Must be an available kernel from "jupyter '
+                             'kernelspec list".')
+
     args = parser.parse_args()
 
     # Set logger level based on verbose flags
@@ -241,4 +255,4 @@ def process_notebooks(nbfile_or_path, exec_only=False, **kwargs):
 
     process_notebooks(args.nbfile_or_path, exec_only=args.exec_only,
                       output_path=output_path, template_file=template_file,
-                      overwrite=args.overwrite)
+                      overwrite=args.overwrite, kernel_name=args.kernel_name)

setup.cfg

@@ -1,20 +1,20 @@
 [build_sphinx]
-source-dir = docs
-build-dir = docs/_build
+source-dir = tutorials
+build-dir = build/sphinx
 all_files = 1
 
 [build_docs]
-source-dir = docs
-build-dir = docs/_build
+source-dir = tutorials
+build-dir = build/sphinx
 all_files = 1
 
 [upload_docs]
-upload-dir = docs/_build/html
+upload-dir = build/sphinx/html
 show-response = 1
 
 [pytest]
 minversion = 2.2
-norecursedirs = build docs/_build
+norecursedirs = build build/sphinx
 doctest_plus = enabled
 
 [ah_bootstrap]

docs/conf.py → tutorials/conf.py

@@ -33,7 +33,7 @@
 # -- General configuration ----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.2'
+needs_sphinx = '1.4'  # needed for suppress_warnings
 
 # To perform a Sphinx version check that needs to be more specific than
 # major.minor, call `check_sphinx_version("x.y.z")` here.
@@ -81,7 +81,8 @@
 html_theme_options = {
     'logotext1': 'astro',  # white,  semi-bold
     'logotext2': 'py',  # orange, light
-    'logotext3': ':tutorials'   # white,  light
+    'logotext3': ':tutorials',   # white,  light
+    'nosidebar': True
     }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -141,8 +142,12 @@
     sys.path.insert(1, _scripts_path)
 
 from convert import process_notebooks
-nb_tutorials_path = os.path.join(_root, 'docs', '_static', 'tutorials')
-template_path = os.path.join(_root, 'docs', '_static', 'astropy.tpl')
-rst_output_path = os.path.join(_root, 'docs', 'rst-tutorials')
+nb_tutorials_path = os.path.join(_root, 'tutorials', 'notebooks')
+template_path = os.path.join(_root, 'tutorials', 'astropy.tpl')
+rst_output_path = os.path.join(_root, 'tutorials', 'rst-tutorials')
 process_notebooks(nb_tutorials_path, output_path=rst_output_path,
                   template_file=template_path)
+
+
+suppress_warnings = ['image.nonlocal_uri']
+html_static_path = ['notebooks']

docs/dev.rst → tutorials/dev.rst

@@ -1,11 +1,11 @@
-Documentation for developers
-============================
+Documentation on tutorials infrastructure
+=========================================
 
 Overview
 --------
 
 Tutorials are written as Jupyter notebooks on the ``master`` branch of the
-``astropy/astropy-tutorials`` repository in ``docs/_static/tutorials/``. These
+``astropy/astropy-tutorials`` repository in ``tutorials/notebooks/``. These
 notebook files do not contain output in order to simplify version-controlling
 the files.
 
@@ -37,7 +37,7 @@ Tutorials directory structure
 -----------------------------
 
 The notebook files must be written as a single Jupyter notebook in a directory
-within the ``docs/_static/tutorials`` directory. The name of the notebook must
+within the ``tutorials/notebooks`` directory. The name of the notebook must
 be the same as the subdirectory name. This is just needed for auto-generating
 links to the source notebooks from the generated RST pages.
 
@@ -48,7 +48,7 @@ You can use the custom nbconvert script in the astropy-tutorials repository to
 test that the tutorials all execute correctly. From the top-level repository
 path::
 
-    python scripts/convert.py docs/_static/tutorials -v --exec-only
+    python scripts/convert.py tutorials/notebooks -v --exec-only
 
 Running the convert script with the flag ``--exec-only`` will just execute the
 notebooks and won't generate RST files. If you have already run the notebooks
@@ -58,16 +58,16 @@ executed. The ``-v`` flag just tells the script to output more "verbose"
 messages, which you may or may not want.
 
 The above command will execute all notebooks in any subdirectory of the
-``docs/_static/tutorials`` path. If you want to just execute a single notebook,
+``tutorials/notebooks`` path. If you want to just execute a single notebook,
 you can specify the path to a single notebook file, e.g.::
 
-    python scripts/convert.py docs/_static/tutorials/coordinates/coordinates.ipynb -v --exec-only
+    python scripts/convert.py tutorials/notebooks/coordinates/coordinates.ipynb -v --exec-only
 
 You can also do this when running and generating RST files, which can be useful
 when writing a new tutorial to make sure it renders in RST properly. To do
 this, just remove the ``--exec-only`` flag::
 
-    python scripts/convert.py docs/_static/tutorials/coordinates/coordinates.ipynb -v
+    python scripts/convert.py tutorials/notebooks/coordinates/coordinates.ipynb -v
 
 Releases
 --------
@@ -84,4 +84,3 @@ Marking a cell with an intentional error
 Edit the cell metadata of the cell in which you would like to raise an exception
 and add the following to the top-level JSON: ``"tags": ["raises-exception"]``
 This tag is recognized by the latest (master) version of nbconvert.
-

tutorials/notebooks/vo/requirements.txt

@@ -0,0 +1 @@
+astroquery