Merge pull request stac-utils#44 from azavea/rde/stac-sprint-tutorial

Fix up docs

Author: lossyrob

README.md

@@ -90,6 +90,8 @@ To build and develop the documentation locally, make sure sphinx is available (w
 
 Use 'make' without arguments to see a list of available commands.
 
+__Note__: `nbsphinx` requires that a local `pystac` is installed; use `pip install -e .`.
+
 
 
 ## Runing the quickstart and tutorials

docs/concepts.rst

@@ -1,7 +1,7 @@
 Concepts
 ########
 
-This page will give an overview of some important concepts to understand when working with PySTAC. If you want to check code examples, see the Jupyter notebook `tutorials in the GitHub repo <https://github.com/azavea/pystac/tree/develop/tutorials>`_.
+This page will give an overview of some important concepts to understand when working with PySTAC. If you want to check code examples, see the :ref:`tutorials`.
 
 Reading STACs
 =============

docs/conf.py

@@ -14,10 +14,17 @@
 #
 import os
 import sys
+import subprocess
 sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('../'))
 from pystac.version import __version__
 
+git_branch = subprocess.check_output(['git',
+                                      'rev-parse',
+                                      '--abbrev-ref',
+                                      'HEAD']) \
+                       .decode("utf-8") \
+                       .strip()
 
 # -- Project information -----------------------------------------------------
 
@@ -45,10 +52,16 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
     'sphinx.ext.githubpages',
+    'sphinx.ext.extlinks',
     'sphinxcontrib.fulltoc',
     'nbsphinx'
 ]
 
+extlinks = {
+    'tutorial': ('https://github.com/azavea/pystac/'
+                  'tree/{}/docs/tutorials/%s'.format(git_branch), 'tutorial')
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

docs/tutorials.rst

@@ -1,18 +1,28 @@
+.. _tutorials:
+
 Tutorials
 #########
 
-The tutorials below are available on GitHub: https://github.com/azavea/pystac/tree/develop/docs/tutorials
-
 PySTAC Introduction
 -------------------
 
-:ref:`This notebook </tutorials/pystac-introduction.ipynb>` gives an introduction to PySTAC concepts through code examples.
+- :tutorial:`GitHub version <pystac-introduction.ipynb>`
+- :ref:`Docs version </tutorials/pystac-spacenet-tutorial.ipynb>`
+
+This tutorial gives an introduction to PySTAC concepts through code examples.
 
 PySTAC SpaceNet tutorial
 ------------------------
 
-:ref:`This notebook </tutorials/pystac-spacenet-tutorial.ipynb>` shows how to create and manipulate a STAC of `SpaceNet <https://spacenetchallenge.github.io/>`_ data.
+- :tutorial:`GitHub version <pystac-spacenet-tutorial.ipynb>`
+- :ref:`Docs version </tutorials/pystac-spacenet-tutorial.ipynb>`
+
+This tutorial shows how to create and manipulate a STAC of `SpaceNet <https://spacenetchallenge.github.io/>`_ data.
 
 How to create STAC Catalogs with PySTAC
 ---------------------------------------
-:ref:`This notebook </tutorials/how-to-create-stac-catalogs.ipynb>` is a tutorial that was part of a 30 minute presentation at the `community STAC sprint <https://github.com/radiantearth/community-sprints/tree/master/11052019-arlignton-va>`_ in Arlington, VA in November 2019. It runs through creating a STAC of image or label items from the `SpaceNet 5 <https://www.topcoder.com/challenges/30099956>`_ dataset.
+
+- :tutorial:`GitHub version <how-to-create-stac-catalogs.ipynb>`
+- :ref:`Docs version </tutorials/how-to-create-stac-catalogs.ipynb>`
+
+This was a tutorial that was part of a 30 minute presentation at the `community STAC sprint <https://github.com/radiantearth/community-sprints/tree/master/11052019-arlignton-va>`_ in Arlington, VA in November 2019. It runs through creating a STAC of image or label items from the `SpaceNet 5 <https://www.topcoder.com/challenges/30099956>`_ dataset.