Merge pull request #348 from MikhailRyazanov/offline

Offline HTML (1st iteration)

.readthedocs.yml

@@ -17,3 +17,4 @@ sphinx:
 # Also build downloadable PDF
 formats:
  - pdf
+ - htmlzip

README.rst

@@ -1,6 +1,9 @@
 PyAbel README
 =============
 
+..
+    Parts between "github-only" comments below are excluded or treated differently by Sphinx (see doc/readme_link.rst)
+
 .. begin-github-only1
 
 .. image:: https://travis-ci.com/PyAbel/PyAbel.svg?branch=master
@@ -18,10 +21,11 @@ Introduction
 
 ``PyAbel`` is a Python package that provides functions for the forward and inverse `Abel transforms <https://en.wikipedia.org/wiki/Abel_transform>`__. The forward Abel transform takes a slice of a cylindrically symmetric 3D object and provides the 2D projection of that object. The inverse Abel transform takes a 2D projection and reconstructs a slice of the cylindrically symmetric 3D distribution.
 
-.. image:: https://user-images.githubusercontent.com/1107796/48970223-1b477b80-efc7-11e8-9feb-c614d6cadab6.png
-    :width: 500px
-    :alt: PyAbel
-    :align: right
+.. begin-github-only2
+
+.. image:: doc/overview.svg
+
+.. end-github-only2
 
 Inverse Abel transforms play an important role in analyzing the projections of angle-resolved photoelectron/photoion spectra, plasma plumes, flames, and solar occultation.
 
@@ -98,8 +102,10 @@ Using PyAbel can be simple. The following Python code imports the PyAbel package
 
     import abel
     original     = abel.tools.analytical.SampleImage().func
-    forward_abel = abel.Transform(original, direction='forward', method='hansenlaw').transform
-    inverse_abel = abel.Transform(forward_abel, direction='inverse', method='three_point').transform
+    forward_abel = abel.Transform(original, direction='forward',
+                                  method='hansenlaw').transform
+    inverse_abel = abel.Transform(forward_abel, direction='inverse',
+                                  method='three_point').transform
 
 Note: the ``abel.Transform()`` class returns a Python ``class`` object, where the 2D Abel transform is accessed through the ``.transform`` attribute.
 
@@ -110,27 +116,28 @@ The results can then be plotted using Matplotlib:
     import matplotlib.pyplot as plt
     import numpy as np
 
-    fig, axs = plt.subplots(1, 2, figsize=(6, 4))
+    fig, axs = plt.subplots(1, 2, figsize=(6, 3))
 
-    axs[0].imshow(forward_abel, clim=(0, np.max(forward_abel) * 0.6),
-                  origin='lower', extent=(-1, 1, -1, 1))
-    axs[1].imshow(inverse_abel, clim=(0, np.max(inverse_abel) * 0.4),
-                  origin='lower', extent=(-1, 1, -1, 1))
+    axs[0].imshow(forward_abel, cmap='ocean_r')
+    axs[1].imshow(inverse_abel, cmap='ocean_r')
 
-    axs[0].set_title('Forward Abel Transform')
-    axs[1].set_title('Inverse Abel Transform')
+    axs[0].set_title('Forward Abel transform')
+    axs[1].set_title('Inverse Abel transform')
 
     plt.tight_layout()
     plt.show()
 
 Output:
 
-.. image:: https://cloud.githubusercontent.com/assets/1107796/13401302/d89aed7e-dec8-11e5-944f-fcafa1b75328.png
-    :width: 400px
-    :alt: example abel transform
+.. begin-github-only3
+
+.. image:: https://user-images.githubusercontent.com/12854133/159737698-30ee69d1-e12d-438a-a9ea-7d7bb0c97f9a.svg
+    :alt: example Abel transform
 
 .. note:: Additional examples can be viewed on the `PyAbel examples <https://pyabel.readthedocs.io/en/latest/examples.html>`__ page and even more are found in the `PyAbel/examples <https://github.com/PyAbel/PyAbel/tree/master/examples>`__ directory.
 
+.. end-github-only3
+
 
 Documentation
 -------------
@@ -210,14 +217,14 @@ First and foremost, please cite the paper(s) corresponding to the implementation
 
 If you find PyAbel useful in you work, it would bring us great joy if you would cite the project. You can find the DOI for the lastest verison at `Zenodo <https://dx.doi.org/10.5281/zenodo.594858>`__.
 
-.. begin-github-only2
+.. begin-github-only4
 
 .. image:: https://zenodo.org/badge/30170345.svg
     :target: https://zenodo.org/badge/latestdoi/30170345
 
-.. end-github-only2
+.. end-github-only4
 
-Additionally, we have written a scientific paper comparing various Abel transform methods. You can find the manuscript at the Review of Scientific Instruments (DOI: `doi.org/10.1063/1.5092635 <https://doi.org/10.1063/1.5092635>`__) or on arxiv (`arxiv.org/abs/1902.09007 <https://arxiv.org/abs/1902.09007>`__).
+Additionally, we have written a scientific paper comparing various Abel transform methods. You can find the manuscript at the Review of Scientific Instruments (DOI: `10.1063/1.5092635 <https://doi.org/10.1063/1.5092635>`__) or on arxiv (`arxiv.org/abs/1902.09007 <https://arxiv.org/abs/1902.09007>`__).
 
 
 **Have fun!**

doc/Makefile

@@ -31,6 +31,7 @@ help:
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
 	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  clean      to delete all generated files"
 #	These aren't tested and probably don't work properly, try at your own risk:
 #	@echo "  pickle     to make pickle files"
 #	@echo "  json       to make JSON files"

doc/conf.py

@@ -93,6 +93,9 @@ def __getattr__(cls, name):
 # The full version, including alpha/beta/rc tags.
 release = version
 
+# Generate/update the DOI file.
+exec(open('conf/doi.py').read())
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -174,10 +177,15 @@ def __getattr__(cls, name):
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['css']
+html_static_path = ['static']
 
 html_css_files = ['custom.css']
 
+html_js_files = []  # MathJax might be added here below
+
+# Try to download MathJax for HTML.
+exec(open('conf/mathjax.py').read())
+
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.

doc/conf/doi.py

@@ -0,0 +1,48 @@
+"""
+Helper script to generate the doi.rst file with the Zenodo DOI corresponding
+to current PyAbel version (if possible, otherwise the default "latest" DOI).
+"""
+
+ver = 'v' + release
+doi_file = 'doi.rst'
+try:
+    # check current file
+    with open(doi_file, 'r') as f:
+        if ' ' + ver + '\n' not in f.read():
+            raise Exception('DOI file needs updating.')
+    print('DOI file is OK.')
+except Exception as e:
+    print(e)
+    print('Retrieving current DOI from Zenodo...')
+    doi = '10.5281/zenodo.594858'  # default (concept) DOI
+    try:
+        from urllib.request import urlopen
+        import json
+        # get info for all versions from Zenodo API
+        # (TODO: can we just get the specific version?)
+        data = json.load(urlopen('https://zenodo.org/api/records/'
+                                 '?q=conceptrecid:594858'
+                                 '&all_versions=True&sort=-version&size=9999'))
+        # search for given version
+        for rec in data['hits']['hits']:
+            md = rec['metadata']
+            if md['version'] == ver:
+                doi = md['doi']
+                break
+        else:
+            raise LookupError('Error: Version {} not found.'.format(ver))
+        print('  Found DOI {} for version {}.'.format(doi, ver))
+    except Exception as e:
+        print('  {}\n  Using concept DOI {}.'.format(e, doi))
+        ver = 'PyAbel'  # don't use specific version
+    # write file
+    with open(doi_file, 'w') as f:
+        f.write('''\
+..
+    DOI for {ver}
+    Don't edit this file, it's updated automatically by conf.py!
+
+.. |doi| replace:: {doi}
+
+.. |doi_link| replace:: `{doi} <https://doi.org/{doi}>`__
+'''.format(ver=ver, doi=doi))

doc/conf/mathjax.py

@@ -0,0 +1,30 @@
+"""
+Helper script for HTML builds: try to download MathJax and use its local copy
+(needed for rendering formulas in offline HTML documentation).
+"""
+
+if any('html' in arg for arg in sys.argv):  # any argument has substring 'html'
+    # URL (most complete standalone script, ~2 MB)
+    mj_url = 'https://github.com/mathjax/MathJax/raw/master/es5/tex-svg-full.js'
+    # local file name
+    mj_file = 'mathjax.js'
+    # relative file path in source tree
+    mj_path = 'static/' + mj_file
+
+    if not os.path.exists(mj_path):
+        print('Downloading MathJax...')
+        try:
+            from urllib.request import urlretrieve
+            urlretrieve(mj_url, mj_path)
+        except Exception as e:
+            print(e)
+
+    if os.path.exists(mj_path):
+        print('Using local MathJax script.')
+        mathjax_path = mj_file  # configure sphinx.ext.mathjax
+        # Sphinx fails to enable MathJax automatically for "single HTML" build
+        if 'singlehtml' in sys.argv:
+            print('  (force inclusion)')
+            html_js_files += [mj_file]  # so add it manually
+    else:
+        print('Local MathJax not found, using default CDN script.')