DOC: Some updates/fixes

Author: mgeier

doc/code-cells.ipynb

@@ -132,6 +132,20 @@
     "\"I'm the 'normal' output\""
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "**Note:**\n",
+    "\n",
+    "Using the IPython kernel, the order is actually mixed up,\n",
+    "see https://github.com/ipython/ipykernel/issues/280.\n",
+    "\n",
+    "</div>"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -240,7 +254,7 @@
    "outputs": [],
    "source": [
     "from IPython.display import Math\n",
-    "eq = Math(r'\\int_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)')\n",
+    "eq = Math(r'\\int\\limits_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)')\n",
     "eq"
    ]
   },
@@ -271,7 +285,7 @@
    "source": [
     "%%latex\n",
     "\\begin{equation}\n",
-    "\\int_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)\n",
+    "\\int\\limits_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)\n",
     "\\end{equation}"
    ]
   },
@@ -318,7 +332,7 @@
     "(see the [ipython_kernel_config.py](ipython_kernel_config.py) in this directory),\n",
     "or in your profile directory\n",
     "(typically `~/.ipython/profile_default/ipython_kernel_config.py`).\n",
-    "If you don't know your IPython profile directory, use this command:\n",
+    "To find out your IPython profile directory, use this command:\n",
     "\n",
     "    python3 -m IPython profile locate\n",
     "\n",

doc/installation.ipynb

@@ -15,7 +15,7 @@
    "source": [
     "# Installation\n",
     "\n",
-    "Note that some packages may be out-of-date.\n",
+    "Note that some packages may be out of date.\n",
     "You can always get the newest `nbsphinx` release from [PyPI](https://pypi.org/project/nbsphinx) (using `pip`).\n",
     "If you want to try the latest development version, have a look at the file [CONTRIBUTING.rst](https://github.com/spatialaudio/nbsphinx/blob/master/CONTRIBUTING.rst).\n",
     "\n",

doc/markdown-cells.ipynb

@@ -69,14 +69,14 @@
    "source": [
     "Equations can also be displayed on their own line like this:\n",
     "\\begin{equation}\n",
-    "\\int_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0).\n",
+    "\\int\\limits_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0).\n",
     "\\end{equation}\n",
     "\n",
     "This can be done by simply using one of the LaTeX math environments, like so:\n",
     "\n",
     "```\n",
     "\\begin{equation}\n",
-    "\\int_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)\n",
+    "\\int\\limits_{-\\infty}^\\infty f(x) \\delta(x - x_0) dx = f(x_0)\n",
     "\\end{equation}\n",
     "```"
    ]
@@ -441,7 +441,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Links to Local Files (HTML only)\n",
+    "## Links to Local Files\n",
     "\n",
     "Links to local files (other than Jupyter notebooks and other Sphinx source files) are also possible, e.g. [requirements.txt](requirements.txt).\n",
     "\n",
@@ -452,7 +452,8 @@
     "```\n",
     "\n",
     "The linked files are automatically copied to the HTML output directory.\n",
-    "For LaTeX output, no link is created."
+    "For LaTeX output, links are created,\n",
+    "but the files are not copied to the target directory."
    ]
   },
   {
@@ -461,12 +462,13 @@
    "source": [
     "## Links to Domain Objects\n",
     "\n",
-    "Links to [Sphinx domain objects](http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html) (such as a Python class or JavaScript function) are also possible. For example: [example_python_function](a-normal-rst-file.rst#example_python_function).\n",
+    "Links to [Sphinx domain objects](http://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html) (such as a Python class or JavaScript function) are also possible. For example:\n",
+    "[example_python_function()](a-normal-rst-file.rst#example_python_function).\n",
     "\n",
     "This was created with:\n",
     "\n",
     "```\n",
-    "[example_python_function](a-normal-rst-file.rst#example_python_function)\n",
+    "[example_python_function()](a-normal-rst-file.rst#example_python_function)\n",
     "```\n",
     "\n",
     "This is especially useful for use with the Sphinx [autodoc](http://www.sphinx-doc.org/en/master/ext/autodoc.html) extension!"

doc/orphan.ipynb

@@ -15,7 +15,7 @@
    "source": [
     "# An Orphan Notebook (HTML Only)\n",
     "\n",
-    "This means that is doesn't appear in a [toctree](http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) (see `index.rst`), but other pages can still link to it ...\n",
+    "This means that it doesn't appear in a [toctree](http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) (see `index.rst`), but other pages can still link to it ...\n",
     "\n",
     "* ... from a [Markdown cell of another notebook](markdown-cells.ipynb#Links-to-Other-Notebooks) using\n",
     "\n",

doc/subdir/toctree.ipynb

@@ -67,7 +67,8 @@
     "Multiple `toctree` cells in a row should be fine, though.\n",
     "\n",
     "The following cell is tagged with `\"nbsphinx-toctree\"` metadata and contains a link to the notebook [yet-another.ipynb](../yet-another.ipynb) and an external link (which will only be visible in the HTML output).\n",
-    "It also contains a section title which will be used as `toctree` caption."
+    "It also contains a section title which will be used as `toctree` caption\n",
+    "(which also will only be visible in the HTML output)."
    ]
   },
   {
@@ -84,7 +85,8 @@
     "\n",
     "[An External Link (HTML only)](https://nbsphinx.readthedocs.io/)\n",
     "\n",
-    "Only the first section title (optional) and links to other sources (and external links) are used, all other cell content is ignored!"
+    "Only the first section title (optional) and links to other sources (and external links) are used,\n",
+    "all other cell content (like this very sentence) is ignored!"
    ]
   }
  ],
@@ -104,9 +106,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.5.1+"
+   "version": "3.7.1"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 1
+ "nbformat_minor": 2
 }

doc/usage.ipynb

@@ -29,7 +29,7 @@
     "Answer the questions that appear on the screen. In case of doubt, just press the `<Return>` key repeatedly to take the default values.\n",
     "\n",
     "After that, there will be a few brand-new files in the current directory.\n",
-    "You'll have to make a few changes to the file named [conf.py](conf.py). You should at least check if those two variables contain the right things:\n",
+    "You'll have to make a few changes to the file named `conf.py`. You should at least check if those two variables contain the right things:\n",
     "\n",
     "```python\n",
     "extensions = [\n",
@@ -39,20 +39,10 @@
     "exclude_patterns = ['_build', '**.ipynb_checkpoints']\n",
     "```\n",
     "\n",
-    "Once your `conf.py` is in place, edit the file named `index.rst` and add the file names of your notebooks (with or without the `.ipynb` extension) to the [toctree](http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) directive.\n",
-    "\n",
-    "<div class=\"alert alert-info\">\n",
+    "For an example, see this project's  [conf.py](conf.py) file.\n",
     "\n",
-    "**autosummary bug:**\n",
-    "\n",
-    "If you are using the `sphinx.ext.autosummary` Sphinx extension, there is [a bug in Sphinx (below version 1.5)](https://github.com/sphinx-doc/sphinx/issues/2485) which prevents notebooks from being parsed. \n",
-    "As a work-around you can explicitly list all the files for which autosummary should be ran using the  [autosummary_generate](http://www.sphinx-doc.org/en/master/ext/autosummary.html#confval-autosummary_generate) variable in `conf.py`.  For example,\n",
-    "\n",
-    "```python\n",
-    "autosummary_generate = ['myfile1.rst', 'myfile2.rst']\n",
-    "```\n",
-    "\n",
-    "</div>"
+    "Once your `conf.py` is in place, edit the file named `index.rst` and add the file names of your notebooks (with or without the `.ipynb` extension) to the [toctree](http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) directive.\n",
+    "For an example, see this project's  [index.rst](index.rst) file."
    ]
   },
   {
@@ -136,18 +126,16 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Automatic Creation of HTML and PDF output on [readthedocs.org](https://readthedocs.org)\n",
+    "## Automatic Creation of HTML and PDF output on readthedocs.org\n",
     "\n",
     "There are two different methods, both of which are described below.\n",
     "\n",
-    "In both cases, you'll first have to create an account on https://readthedocs.org/ and connect your Github/Bitbucket account. Instead of connecting, you can also manually add any publicly available Git/Subversion/Mercurial/Bazaar repository.\n",
+    "In both cases, you'll first have to create an account on https://readthedocs.org/ and connect your GitLab/Github/Bitbucket account. Instead of connecting, you can also manually add any publicly available Git/Subversion/Mercurial/Bazaar repository.\n",
     "\n",
     "After doing the steps described below, you only have to \"push\" to your repository, and the HTML pages and the PDF file of your stuff are automagically created on readthedocs.org. Awesome!\n",
     "\n",
     "You can even have different versions of your stuff, just use Git tags and branches and select in the readthedocs.org settings (under \"Admin\", \"Versions\") which of those should be created.\n",
     "\n",
-    "If your new versions are not automatically built, go to the \"Settings\" of your Github repository, continue to \"Integrations & services\", and make sure that \"ReadTheDocs\" is listed and activated in the \"Services\" section. If not, use \"Add service\". There is probably a similar thing for Bitbucket and others.\n",
-    "\n",
     "<div class=\"alert alert-info\">\n",
     "\n",
     "**Note:**\n",
@@ -222,6 +210,7 @@
     "**Note:**\n",
     "\n",
     "Most of the \"Advanced Settings\" on readthedocs.org will be ignored if you have a `readthedocs.yml` file.\n",
+    "In this file you can control all the settings, see https://docs.readthedocs.io/en/latest/yaml-config.html.\n",
     "\n",
     "</div>\n",
     "\n",
@@ -351,6 +340,7 @@
     "\n",
     "In the Jupyter Notebook application, you can manually clear all outputs by selecting\n",
     "\"Cell\" $\\to$ \"All Output\" $\\to$ \"Clear\" from the menu.\n",
+    "In JupyterLab, the menu items are \"Edit\" $\\to$ \"Clear All Outputs\".\n",
     "\n",
     "There are several tools available to remove outputs from multiple files at once without having to open them separately.\n",
     "You can even include such a tool as \"clean/smudge filters\" into your Git workflow, which will strip the output cells automatically whenever a Git command is executed.\n",
@@ -381,7 +371,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.6.4+"
+   "version": "3.7.1"
   }
  },
  "nbformat": 4,