Add Sphinx extension for glossary referencing: ipypublish.sphinx.gls (

#75)

- Added Sphinx extension for glossary referencing: `ipypublish.sphinx.gls`.
  See :ref:`sphinx_ext_gls`

- Added `ConvertBibGloss` post-processor,
  to convert a bibglossary to the required format

- Added notebook-level metadata options for `bibglossary` and `sphinx`
  (see :ref:`meta_doclevel_schema`)

- Large refactoring and improvements for test suite, particularly for testing
  of Sphinx extensions (using the Sphinx pytest fixtures) and creation of the
  `IpyTestApp` fixture

- fixes #71 

Back-compatibility breaking changes:

- renamed Sphinx notebook extension from
  `ipypublish.ipysphinx` to `ipypublish.sphinx.notebook`
  (see :ref:`sphinx_ext_notebook`)

- `ipypublish.postprocessors.base.IPyPostProcessor.run_postprocess`
  input signature changed (and consequently it has changes for all post-processors)

`v0.9`:

```python
   def run_postprocess(self, stream, filepath, resources):
      output_folder = filepath.parent
```

`v0.10`:

``` python
   def run_postprocess(self, stream, mimetype, filepath, resources):
      output_folder = filepath.parent
```

.coveragerc

@@ -1,6 +1,3 @@
 [run]
 omit = 
-    ipypublish/ipysphinx/docutils_transforms.py
-    ipypublish/ipysphinx/extension.py
-    ipypublish/ipysphinx/directives.py
     ipypublish/scripts/nb_setup.py

.flake8

@@ -0,0 +1,5 @@
+[flake8]
+exclude = 
+    setup.py,
+    ipypublish/scripts/ipynb_latex_setup.py,
+    ipypublish/tests/test_files/basic_nb/expected/python_with_meta.py

.travis.yml

@@ -3,22 +3,37 @@ matrix:
   include:
   - os: linux
     sudo: required
-    python: 2.7
+    python: 3.6
     dist: trusty
+    env: TEST_TYPE="flake8"
   - os: linux
     sudo: required
-    python: 3.4
+    python: 3.6
     dist: trusty
+    env: TEST_TYPE="rtd"
   - os: linux
     sudo: required
-    python: 3.5
+    python: 3.6
     dist: trusty
+    env: TEST_TYPE="pytest" PYPI_DEPLOY=true
   - os: linux
     sudo: required
-    python: 3.6
+    python: 2.7
+    dist: trusty
+    env: TEST_TYPE="pytest"
+  - os: linux
+    sudo: required
+    python: 3.4
     dist: trusty
+    env: TEST_TYPE="pytest"
+  - os: linux
+    sudo: required
+    python: 3.5
+    dist: trusty
+    env: TEST_TYPE="pytest"
   - os: osx
     language: generic
+    env: TEST_TYPE="pytest"
     before_install:
     - travis_wait brew update
     # TODO currently by default python 2.7 is already installed (see https://github.com/travis-ci/travis-ci/issues/9929)
@@ -51,59 +66,72 @@ matrix:
     - travis_retry sudo tlmgr install biblatex
     - travis_retry sudo tlmgr install needspace
     - travis_retry sudo tlmgr install collection-fontsrecommended
+    # glossaries dependencies
+    - travis_retry sudo tlmgr install glossaries  # NB: for different languages glossaries-<language>
+    - travis_retry sudo tlmgr install mfirstuc  # see https://tex.stackexchange.com/questions/268216/usepackageglossaries-wont-work-after-miktex-update-reinstallation
+    - travis_retry sudo tlmgr install xfor
+    - travis_retry sudo tlmgr install datatool
+    - travis_retry sudo tlmgr install substr
   allow_failures:
     - os: linux
       sudo: required
       python: 3.4
       dist: trusty
+      env: TEST_TYPE="pytest"
     - os: linux
       sudo: required
       python: 3.5
       dist: trusty
+      env: TEST_TYPE="pytest"
     - os: osx
       language: generic
-
-# TODO add read the docs test `pip install .[docs] cd docs; make`
+      env: TEST_TYPE="pytest"
 
 before_install:
 # Pandoc
-- url="https://github.com/jgm/pandoc/releases/tag/2.6"
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then path=$(curl -L $url | grep -o '/jgm/pandoc/releases/download/.*-amd64\.deb') ; fi
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then downloadUrl="https://github.com$path" ; fi
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then file=${path##*/} ; fi
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then wget $downloadUrl && sudo dpkg -i $file ; fi
+- |
+  if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then
+    url="https://github.com/jgm/pandoc/releases/tag/2.6"
+    path=$(curl -L $url | grep -o '/jgm/pandoc/releases/download/.*-amd64\.deb')
+    downloadUrl="https://github.com$path"
+    file=${path##*/}
+    wget $downloadUrl && sudo dpkg -i $file
+  fi
 # LaTeX
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get -qq update ; fi
-# - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get install -y pandoc ; fi
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get install -y texlive ; fi
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get install -y texlive-xetex ; fi
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get install -y texlive-latex-extra ; fi
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get install -y texlive-lang-portuguese ; fi
-# need up-to-date koma-script, which isn't supplied with this version of debian
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo wget http://mirrors.ctan.org/install/macros/latex/contrib/koma-script.tds.zip ; fi
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo unzip koma-script.tds.zip -d ~/texmf/ ; fi
-- if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then sudo apt-get install -y latexmk ; fi
-- pip install -U pip setuptools wheel
+- |
+  if [[ "$TRAVIS_OS_NAME" == "linux" && "$TEST_TYPE" == "pytest" ]]; then
+    sudo apt-get -qq update
+    # sudo apt-get install -y pandoc is too old
+    sudo apt-get install -y texlive
+    sudo apt-get install -y texlive-xetex
+    sudo apt-get install -y texlive-latex-extra
+    sudo apt-get install -y texlive-lang-portuguese
+    # texlive-glossaries doesn't appear to be available
+    sudo wget http://mirrors.ctan.org/install/macros/latex/contrib/glossaries.tds.zip
+    sudo unzip glossaries.tds.zip -d ~/texmf/
+    # need up-to-date koma-script, which isn't supplied with this version of debian
+    sudo wget http://mirrors.ctan.org/install/macros/latex/contrib/koma-script.tds.zip
+    sudo unzip koma-script.tds.zip -d ~/texmf/
+    sudo apt-get install -y latexmk
+  fi
+
 install:
-- travis_wait pip install .[tests,sphinx]
-- pip install --quiet coveralls
+- pip install -U pip setuptools wheel
+- if [[ "$TEST_TYPE" == "pytest" ]]; then travis_wait pip install .[tests] ; fi
+- if [[ "$TEST_TYPE" == "pytest" ]]; then pip install --quiet coveralls ; fi
+- if [[ "$TEST_TYPE" == "flake8" ]]; then travis_wait pip install "flake8(>=3.7,<3.8)" ; fi
+- if [[ "$TEST_TYPE" == "rtd" ]]; then travis_wait pip install .[rtd] ; fi
+
 script:
-# - nosetests -v --nocapture --with-doctest --with-coverage --exe --cover-package=ipypublish
-- pytest -v --cov=ipypublish --cov-config .coveragerc --cov-report= ipypublish
-- nbpublish -pdf --pdf-debug -log debug example/notebooks/Example.ipynb
+- if [[ "$TEST_TYPE" == "pytest" ]]; then pytest -v --cov=ipypublish --cov-config .coveragerc --cov-report= ipypublish ; fi
+- if [[ "$TEST_TYPE" == "pytest" ]]; then nbpublish -pdf --pdf-debug -log debug example/notebooks/Example.ipynb ; fi
+- if [[ "$TEST_TYPE" == "flake8" ]]; then flake8 . ; fi
+- if [[ "$TEST_TYPE" == "rtd" ]]; then cd docs; make ; fi
+
 after_success:
-- coveralls
+- if [[ "$TEST_TYPE" == "pytest" ]]; then coveralls ; fi
+
 deploy:
-#  - provider: pypi
-#    distributions: bdist_wheel
-#    server: https://test.pypi.org/legacy/
-#    user: cjsewell
-#    password:
-#      secure: en0mNL9+rzlhUpnsLsdd3kskGYWVHL+bUyKnPJCZq0d0AH7tmAC7/J+KkR9iv+pHwVHJphqd+8X3p7k+eXOjjSGlY4mnTmz84iQrRilRzEsK53IvlU+0tayKv23ZlUVG8ecKT/33BOdqO/QZNOz09DViTABj65iIoTzd3pM1b94ycCOjWJV2EzSn8UQXe0p90mO7iE4aoyOOimweezbaZ1FrmZatUuRWeFGuzhopHF1FHtd/xk8Q2rWItUqwIgHiESknAAm5fFsgfJtEqenvmoGbeuBJ7ImCQzEOtF30Im7HJRwd8tXRJHVrTS0PpQpZLjhS/nGors8RRC0DW7r1FdYTUKWUUypDZJSphpyAkfvdVtlOX0NBBuCU71X8yx3yZWLsSv84PulRN6YASPSV3FvptMtam1J2/eoAm2aNy+/RyCvZpe8VtlE+7CSQX41T/1FdIyMzThlJHG0n3Kx92YBTUVuNLTlawTfK4WfS8NJhW1H74XoIRzrKn41EVoup4G0HAPj3vFhezwMdJ7CFIPyav5RdYf3h60smE0qpJl+qIMo5QD7AEWpvg+AIR8C4e0fRE6Iqovqzk+vM4Jq1QlI/mghDkRTFKEES5v0dObaIG8Gi+F3TfBjlyssHA0YREBaZRfVaO2Ov8wLBNaqr3QyJniJ5+eK2yL406DCqKOc=
-#    on:
-#      branch: master
-#      tags: false
-#      condition: $TRAVIS_PYTHON_VERSION = "3.6"
   - provider: pypi
     distributions: "bdist_wheel sdist"
     user: cjsewell
@@ -112,4 +140,4 @@ deploy:
     on:
       branch: master
       tags: true
-      condition: $TRAVIS_PYTHON_VERSION = "3.6"
+      condition: $PYPI_DEPLOY = true

.vscode/jinja2-latex.code-snippets

@@ -0,0 +1,76 @@
+{
+    "super": {
+        "prefix": "super",
+        "scope": "jinja-latex",
+        "body": "((( super() )))",
+        "description": "call inherited block"
+    },
+    "set": {
+        "prefix": "set",
+        "scope": "jinja-latex",
+        "body": "((* set ${1:name} = ${2:value} *))",
+        "description": "set variable"
+    },   
+    "print": {
+        "prefix": "print",
+        "scope": "inja-latex",
+        "body": "((( ${1:variable} )))",
+        "description": "print variable"
+    },   
+    "block": {
+        "prefix": "block",
+        "scope": "jinja-latex",
+        "body": [
+          "((* block ${1:name} *))",
+          "$2",
+          "((* endblock ${1:name} *))"
+        ],
+        "description": "jinja block"
+    },
+    "macro": {
+        "prefix": "macro",
+        "scope": "jinja-latex",
+        "body": [
+          "((* macro ${1:name} *))",
+          "$2",
+          "((* endmacro *))"
+        ],
+        "description": "macro function"
+    },
+    "if": {
+        "prefix": "if",
+        "scope": "jinja-latex",
+        "body": [
+          "((* if ${1:condition} *))",
+          "$2",
+          "((* endif *))"
+        ],
+        "description": "if condition"
+    },
+    "if-else": {
+        "prefix": "if-else",
+        "scope": "jinja-latex",
+        "body": [
+          "((* if ${1:condition} *))",
+          "$2",
+          "((* else *))",
+          "$3",
+          "((* endif *))"
+        ],
+        "description": "if-else condition"
+    },
+    "if-elif-else": {
+        "prefix": "if-elif-else",
+        "scope": "jinja-latex",
+        "body": [
+          "((* if ${1:condition} *))",
+          "$2",
+          "((* else *))",
+          "$3",
+          "((* elif ${1:condition2} *))",
+          "",
+          "((* endif *))"
+        ],
+        "description": "if-else condition"
+    }
+}

.vscode/settings.json

@@ -29,11 +29,13 @@
     "latex-workshop.latex.autoBuild.onSave.enabled": false,
     "cSpell.words": [
         "Jupyter",
+        "docutils",
         "ipynb",
         "ipypublish",
         "jupytext",
         "nbconvert",
         "nbpresent",
+        "noqa",
         "placeholders",
         "plugins"
     ],

MANIFEST.in

@@ -4,5 +4,5 @@ include requirements.txt
 recursive-include ipypublish *.json
 recursive-include ipypublish *.j2
 recursive-include ipypublish *.yaml
-recursive-include ipypublish/ipysphinx/css *.css
-recursive-include ipypublish/tests/test_files *
+recursive-include ipypublish/sphinx/notebook/css *.css
+include ipypublish/tests/test_files/example.jpg

conftest.py

@@ -0,0 +1 @@
+pytest_plugins = 'sphinx.testing.fixtures'

docs/environment.yaml

@@ -2,4 +2,8 @@ channels:
   - conda-forge
 dependencies:
   - python =3.6
+  # TODO pip>=10 fails du to this issue https://github.com/pypa/pip/issues/5247
+  # raises error `Cannot uninstall 'docutils'. It is a distutils installed project`
+  # even though docutils appear to already be at the correct version (0.14)!?
+  - pip <10.0
   - pandoc

docs/get_intersphinx_inv.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python 
+#!/usr/bin/env python
 
 
 def fetch_inventory(uri):
@@ -26,7 +26,9 @@ def warn(self, msg):
     # uri = "https://docutils.readthedocs.io/en/sphinx-docs/objects.inv"
     # uri = "https://traitlets.readthedocs.io/en/latest/objects.inv"
     # uri = "https://networkx.github.io/documentation/stable/objects.inv"
-    uri = "http://docs.scipy.org/doc/scipy/reference/objects.inv"
+    # uri = "http://docs.scipy.org/doc/scipy/reference/objects.inv"
+    # uri = "http://pillow.readthedocs.org/en/latest/objects.inv"
+    uri = 'http://www.sphinx-doc.org/en/latest/objects.inv'
 
     # Read inventory into a dictionary
     inv = fetch_inventory(uri)

docs/source/_static/example_glossary.bib

@@ -0,0 +1,24 @@
+@glsterm{gtkey1,
+    name = {name},
+    description = {full description \textbf{with latex}},
+    plural = {some names},
+    text = {alternative text},
+    sort = {a},
+    symbol = {\ensuremath{n}}
+}
+
+@glsacronym{akey1,
+    abbreviation = {MA},
+    longname = {My Abbreviation},
+    description = {full description},
+    plural = {MAs},
+    longplural = {Some Abbreviations}
+}
+
+@glssymbol{symbol1,
+    name = {\ensuremath{\pi}},
+    description = {full description},
+    plural = {\ensuremath{\pi}s},
+    text = {alternative text},
+    sort = {b}
+}

docs/source/_static/other_glossary.bib

@@ -0,0 +1,24 @@
+@glsterm{gtkey2,
+    name = {name},
+    description = {full description \textbf{with latex}},
+    plural = {some names},
+    text = {alternative text},
+    sort = {a},
+    symbol = {\ensuremath{n}}
+}
+
+@glsacronym{akey2,
+    abbreviation = {MA},
+    longname = {My Abbreviation},
+    description = {full description},
+    plural = {MAs},
+    longplural = {Some Abbreviations}
+}
+
+@glssymbol{symbol2,
+    name = {\ensuremath{\pi}},
+    description = {full description},
+    plural = {\ensuremath{\pi}s},
+    text = {alternative text},
+    sort = {b}
+}

docs/source/api/ipypublish.schema.rst

@@ -1,5 +1,5 @@
-ipypublish\.schema package
-==========================
+ipypublish.schema package
+=========================
 
 Module contents
 ---------------

docs/source/code_cells.ipynb

@@ -155,8 +155,7 @@
    "outputs": [],
    "source": [
     "import os\n",
-    "from ipypublish.tests import TEST_FILES_DIR\n",
-    "example_pic = os.path.join(TEST_FILES_DIR, 'example.jpg')"
+    "from ipypublish.tests import TEST_PIC_PATH\n"
    ]
   },
   {
@@ -173,7 +172,7 @@
    },
    "outputs": [],
    "source": [
-    "nb_setup.images_hconcat([example_pic, example_pic],\n",
+    "nb_setup.images_hconcat([TEST_PIC_PATH, TEST_PIC_PATH],\n",
     "               width=600, gap=10)"
    ]
   },
@@ -192,7 +191,7 @@
    },
    "outputs": [],
    "source": [
-    "nb_setup.images_vconcat([example_pic, example_pic],\n",
+    "nb_setup.images_vconcat([TEST_PIC_PATH, TEST_PIC_PATH],\n",
     "               height=400, gap=10)"
    ]
   },
@@ -211,7 +210,7 @@
    },
    "outputs": [],
    "source": [
-    "nb_setup.images_gridconcat([[_,_] for _ in [example_pic, example_pic]],\n",
+    "nb_setup.images_gridconcat([[_,_] for _ in [TEST_PIC_PATH, TEST_PIC_PATH]],\n",
     "               height=300, vgap=10,hgap=20)"
    ]
   },