Merge pull request #528 from geoscixyz/ref/intro-apps

Ref/intro apps

Author: lheagy

.bumpversion.cfg

@@ -0,0 +1,4 @@
+[bumpversion]
+current_version = 0.0.2
+files = conf.py _templates/footer.html
+

_ext/autodoc.py

@@ -8,10 +8,10 @@
 CONTRIB_INFO = ['affiliation', 'location', 'email', 'url', 'ORCID']
 CASEHISTORY_INFO = ['citations', 'contributors', 'tags']
 
-ORCID_URL = 'http://orcid.org/'
+ORCID_URL = u'http://orcid.org/'
 
 THIS_IS_AUTOGENERATED = (
-    ".. --------------------------------- ..\n"
+    u".. --------------------------------- ..\n"
     "..                                   ..\n"
     "..    THIS FILE IS AUTO GENEREATED   ..\n"
     "..                                   ..\n"
@@ -34,7 +34,7 @@ def make_formula_sheet():
         (fName.split(os.path.sep)[:-2] + ['content', 'equation_bank' + '.rst'])
     )
 
-    out = """.. _equation_bank:
+    out = u""".. _equation_bank:
 
 {}
 
@@ -149,12 +149,12 @@ def make_contributorslist(fpath='contributors.json',
             html_block = '<br>'.join(html_block)
 
             if 'avatar' in contrib:
-                avatar = """
+                avatar = u"""
         <a class="reference internal image-reference" href="{avatar}"><img alt="{avatar}" class="align-left" src="{avatar}" style="width: 120px; border-radius: 10px; vertical-align: text-middle padding-left="20px" /></a>
                 """.format(avatar=contrib['avatar'])
 
             else:
-                avatar = ""
+                avatar = u""
 
             out = u"""
 
@@ -202,7 +202,7 @@ def make_case_histories(fpath='content/case_histories/case_histories.json',
     fpath = open(fpath)  # file to write to
     casehistories = json.load(fpath)  # casehistories json
 
-    out = """
+    out = u"""
 
 {}
 
@@ -213,12 +213,12 @@ def make_case_histories(fpath='content/case_histories/case_histories.json',
     f = open(fout, 'w')
     f.write(out)
 
-    toctree = """
+    toctree = u"""
     """.join(
         ["{}/index".format(key) for key in casehistories.keys()]
     )
 
-    toctreeblock = """
+    toctreeblock = u"""
 .. toctree::
     :maxdepth: 1
     :hidden:
@@ -266,7 +266,7 @@ def make_case_histories(fpath='content/case_histories/case_histories.json',
 
             contributions = '\n'.join(contributions)
 
-            contributors_block="""
+            contributors_block=u"""
 - Contributors
 {contributions}
 """.format(contributions=contributions)
@@ -287,7 +287,7 @@ def make_case_histories(fpath='content/case_histories/case_histories.json',
 
             tags_list = '\n'.join(tags_list)
 
-            tags_block="""
+            tags_block=u"""
 - Tags
 {tags_list}
 """.format(tags_list=tags_list)

_ext/includeMath.py

@@ -0,0 +1,52 @@
+
+"""
+    Adapted from sphinx.ext.purpose
+
+    https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/purpose.py
+
+    Allow purposes to be inserted into your documentation.  Inclusion of purposes can
+    be switched of by a configuration variable.  The purposelist directive collects
+    all purposes of your project and lists them along with a backlink to the
+    original location.
+    :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+
+import sphinx
+# from sphinx.locale import _
+# from sphinx.environment import NoUri
+# from sphinx.util.nodes import set_source_info
+# from docutils.parsers.rst import Directive
+# from docutils.parsers.rst.directives.admonitions import BaseAdmonition
+
+from docutils.parsers.rst.directives.misc import Include
+
+from sphinx.ext.mathbase import setup_math
+
+class IncludeMath(setup_math):
+    """
+    Includes equations and allows them to be labeled
+    """
+
+    def run(self):
+        # type: () -> List[nodes.Node]
+        print(self.options)
+        env = self.state.document.settings.env
+        # if self.arguments[0].startswith('<') and \
+        #    self.arguments[0].endswith('>'):
+        #     # docutils "standard" includes, do not do path processing
+        #     return Include.run(self)
+        rel_filename, filename = env.relfn2path(self.arguments[0])
+        self.arguments[0] = filename
+        print(dir(env))
+        env.note_included(filename)
+        nodes = Include.run(self)
+        print(dir(nodes))
+        return nodes
+
+
+def setup(app):
+    directives.register_directive('includemath', IncludeMath)

_templates/footer.html

@@ -39,12 +39,16 @@
             <a href="http://geosci.xyz/contact">Contact</a>
         </div>
         <br>
+        <div class="col-md-8" align="left" font-size="11px">
+            <a href="https://github.com/geoscixyz/em/releases/tag/0.0.2">Version 0.0.2</a>
+        </div>
+        <br>
         <div class="col-md-8" align="left" font-size="11px">
             <div class="row">
                 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/" width="60px"; style="float:right;height:3em;line-height:3em;padding:10px 0 0 1em;">
                     <img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/4.0/88x31.png" />
                 </a>
-                2015-2017,
+                2015-2018,
                 <a href="http://geosci.xyz">GeoSci Developers.</a><br />
                 Except where noted, this work is licensed under a <br />
                 <a rel="license" href="http://creativecommons.org/licenses/by/4.0/">

apps.rst

@@ -13,9 +13,6 @@ There are two categories of notebooks
 - :ref:`Simulation Notebooks <simulation_notebooks>`
     - **Purpose:** To be a starting point for getting up and running with the EM Module of SimPEG for performing numerical simulations and inversions
 
-.. We have provided instructions on working with the apps in the `Jupyter
-.. Notebook<http://jupyter.org>`_ environment.
-
 If you run into any issues, please let us know at: http://github.com/geoscixyz/em_apps.
 
 
@@ -24,40 +21,122 @@ If you run into any issues, please let us know at: http://github.com/geoscixyz/e
 EM Apps
 -------
 
-There are a few ways you can run the notebooks. We recommend:
+.. image:: https://mybinder.org/badge.svg
+    :target: https://mybinder.org/v2/gh/geoscixyz/em-apps/master?filepath=index.ipynb
+    :alt: Binder
 
-- Microsoft Azure (free, login required): https://notebooks.azure.com/lheagy/libraries/em_apps
-- Binders (free, no login required): https://mybinder.org/v2/gh/geoscixyz/em_apps/master
-- or can be downloaded from Github (free, installation of python required): http://github.com/geoscixyz/em_apps
+.. image:: https://notebooks.azure.com/launch.png
+    :target: https://notebooks.azure.com/import/gh/geoscixyz/em-apps
+    :alt: Azure notebooks
 
 .. image:: images/DC_LayeredEarth_notebook.png
+    :width: 45%
+    :alt: dc-layered-earth-app
+    :align: right
+
+There are a few ways you can run the notebooks. We provide instructions using:
+
+- :ref:`Binder <binder>` (free, no login required)
+- :ref:`Microsoft Azure <azure>` (free, login required)
+
+Alternatively, they can be downloaded from GitHub and run locally.
+Please see instructions at: https://github.com/geoscixyz/em-apps
+
+
+
+
+.. _jupyter_notebooks:
+
+Jupyter Notebooks
+^^^^^^^^^^^^^^^^^
 
 Within the Jupyter Notebook environment, you can use :code:`shift + enter` to run
 each cell of code, or from the menu, select :code:`cell, run all`
 
 .. image:: images/run_all_cells.png
 
 
-Notebooks include
-^^^^^^^^^^^^^^^^^
+.. _binder:
+
+Binder
+^^^^^^
+
+.. image:: https://mybinder.org/badge.svg
+    :target: https://mybinder.org/v2/gh/geoscixyz/em-apps/master?filepath=index.ipynb
+    :alt: Binder
+
+
+1. Launch the binder by clicking on the badge above or going to: https://mybinder.org/v2/gh/geoscixyz/em-apps/master?filepath=index.ipynb.
+   This can sometimes take a couple minutes, so be patient...
+
+2. Select the notebook of interest from the contents
+
+3. :ref:`Run the jupyter notebook <jupyter_notebooks>`
+
+.. image:: images/binder-steps.png
+    :alt: binder-steps
+    :width: 100%
+    :align: center
 
-.. image:: images/notebook_list.png
+
+
+.. _azure:
+
+Azure Notebooks
+^^^^^^^^^^^^^^^
+
+.. image:: https://notebooks.azure.com/launch.png
+    :target: https://notebooks.azure.com/import/gh/geoscixyz/em-apps
+    :alt: Azure notebooks
+
+1. Navigate to Azure notebooks by clicking on the badge above or going to: https://notebooks.azure.com/import/gh/geoscixyz/em-apps,
+   and select :code:`Import` to import the library
+
+2. Sign in to your microsoft account (or `Create One` if you do not already have an account)
+
+3. Create the new library. Select `Clone recursively` in order to import the required packages. Select Import
+
+4. Select :code:`index.ipynb` to view the notebook contents
+
+5. Select the notebook of interest from the contents
+
+6. :ref:`Run the jupyter notebook <jupyter_notebooks>`
+
+.. image:: images/azure-steps.png
+    :alt: binder-steps
+    :width: 100%
+    :align: center
 
 
 .. _simulation_notebooks:
 
 Simulation Notebooks
 --------------------
 
+
+.. image:: ./images/FDEM_sounding_over_sphere.png
+    :width: 45%
+    :alt: dc-layered-earth-app
+    :align: right
+
+.. image:: https://mybinder.org/badge.svg
+    :target: https://mybinder.org/v2/gh/simpeg/em-notebooks/master?filepath=index.ipynb
+    :alt: Binder
+
+.. image:: https://notebooks.azure.com/launch.png
+    :target: https://notebooks.azure.com/import/gh/simpeg/em-notebooks
+    :alt: Azure notebooks
+
 These notebooks walk through forward simulations of both frequency domain
 electromagnetics and time domain electromagnetics using `SimPEG <http://simpeg.xyz>`_.
 
-These notebooks are available at
+See the above instructions to run the notebooks from Binder or Azure. Note that the url's are different.
 
-- Microsoft Azure (free, login required): https://notebooks.azure.com/lheagy/libraries/electromagnetics
-- Binders (free, no login required): https://mybinder.org/v2/gh/simpeg/em_notebooks/master
-- or can be downloaded from Github (free, installation of python required): http://github.com/simpeg/em_notebooks
+- :ref:`Binder <binder>` (free, no login required): https://mybinder.org/v2/gh/simpeg/em-notebooks/master?filepath=index.ipynb
+- :ref:`Microsoft Azure <azure>` (free, login required): https://notebooks.azure.com/import/gh/simpeg/em-notebooks
+
+Alternatively, they can be downloaded from GitHub and run locally.
+Please see instructions at: https://github.com/simpeg/em-notebooks
 
 Further examples and documentation are available at http://simpeg.xyz.
 
-.. image:: ./images/FDEM_sounding_over_sphere.png

conf.py

@@ -100,9 +100,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = ''
+version = '0.0.2'
 # The full version, including alpha/beta/rc tags.
-release = ''
+release = '0.0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -143,9 +143,11 @@
     'https://gif.eos.ubc.ca/sites/default/files/McMillan_parametric.pdf',
     'http://seg.org',
     'http://library.seg.org/doi/',
-    'https://notebooks.azure.com/lheagy/libraries/electromagnetics',
-    'https://notebooks.azure.com/lheagy/libraries/em_apps',
     'http://www.publish.csiro.au/EX/pdf/ASEG2016ab212',
+    'https://notebooks.azure.com/import/gh/geoscixyz/em-apps',
+    'https://notebooks.azure.com/import/gh/simpeg/em-notebooks',
+    'https://www.onepetro.org/conference-paper/SEG-2012-1478',
+    'https://doi.org/*',
                     ]
 linkcheck_retries = 3
 linkcheck_timeout = 900

content/case_histories/bookpurnong/index.rst

@@ -11,7 +11,11 @@ Bookpurnong
 
 **Special Thanks**
 
-Thanks to the `Society of Exploration Geophysicists <http://seg.org>`__ and SkyTEM for permission to reproduce figures and adapt text from the source material. This case history is based upon two articles: `Spatially constrained inversion for quasi 3D modelling of airborne electromagnetic data – an application for environmental assessment in the Lower Murray Region of South Australia <http://library.seg.org/doi/abs/10.1071/EG08027>`_ by Viezzoli, Auken and Munday :cite:`viezzoli2009` and `Accurate  quasi  3D  versus  practical  full  3D  inversion  of  AEM  data – the  Bookpurnong  case  study <http://www.hgg.geo.au.dk/Papers_EndNote/0477620876/VIEZZOLI2010C.pdf>`_ by Viezzoli, Munday, Auken and Christiansen :cite:`viezzoli2010`.
+Thanks to the `Society of Exploration Geophysicists <http://seg.org>`__ and SkyTEM for permission to reproduce figures and
+adapt text from the source material. This case history is based upon two articles:
+
+- `Spatially constrained inversion for quasi 3D modelling of airborne electromagnetic data – an application for environmental assessment in the Lower Murray Region of South Australia <http://library.seg.org/doi/abs/10.1071/EG08027>`_ by Viezzoli, Auken and Munday :cite:`viezzoli2009` and
+- `Accurate  quasi  3D  versus  practical  full  3D  inversion  of  AEM  data – the  Bookpurnong  case  study <http://www.hgg.geo.au.dk/Papers_EndNote/0477620876/VIEZZOLI2010C.pdf>`_ by Viezzoli, Munday, Auken and Christiansen :cite:`viezzoli2010`.
 
 **Abstract**