{ "cells": [ { "cell_type": "markdown", "metadata": { "nbsphinx": "hidden" }, "source": [ "This notebook is part of the `nbsphinx` documentation: http://nbsphinx.readthedocs.org/." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "# Usage\n", "\n", "Install `nbsphinx` with [pip](https://pip.pypa.io/en/latest/installing/):\n", "\n", " pip install nbsphinx --user\n", "\n", "If you change your mind, you can un-install it with:\n", "\n", " pip uninstall nbsphinx" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Sphinx Setup\n", "\n", "In the directory with your notebook files, run this command (assuming you have [Sphinx](http://sphinx-doc.org/) installed already):\n", "\n", " sphinx-quickstart\n", " \n", "Answer the questions that appear on the screen. In case of doubt, just press the `` key 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", "\n", "```python\n", "extensions = [\n", " 'nbsphinx',\n", " 'sphinx.ext.mathjax',\n", "]\n", "exclude_patterns = ['_build', '**.ipynb_checkpoints']\n", "```\n", "\n", "Once your `conf.py` is in place, edit the file named [index.rst](index.rst) and add the file names of your notebooks (with or without the `.ipynb` extension) to the `toctree` directive." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Running Sphinx\n", "\n", "To create the HTML pages, use this command:\n", "\n", " sphinx-build \n", " \n", "If you have many notebooks, you can do a parallel build by using the `-j` option:\n", "\n", " sphinx-build -j\n", "\n", "For example, if your source files are in the current directory and you have 4 CPU cores, you can run this:\n", "\n", " sphinx-build . _build -j4\n", " \n", "Afterwards, you can find the main HTML file in `_build/index.html`.\n", "\n", "Subsequent builds will be faster, because only those source files which have changed will be re-built.\n", "To force re-building all source files, use the `-E` option.\n", "\n", "To create LaTeX output, use:\n", "\n", " sphinx-build -b latex\n", "\n", "If you don't know how to create a PDF file from the LaTeX output, you should have a look at [Latexmk](http://users.phys.psu.edu/~collins/software/latexmk-jcc/) (see also [this tutorial](http://mg.readthedocs.org/latexmk.html)).\n", "\n", "Sphinx can automatically check if the links you are using are still valid.\n", "Just invoke it like this:\n", "\n", " sphinx-build -b linkcheck" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Watching for Changes with `sphinx-autobuild`\n", "\n", "If you think it's tedious to run the command `sphinx-build` again and again when you make changes to your notebooks, you'll be happy to hear that there is a way to avoid that: [sphinx-autobuild](https://pypi.python.org/pypi/sphinx-autobuild)!\n", "\n", "It can be installed with\n", "\n", " pip install sphinx-autobuild --user\n", " \n", "You can start auto-building your files with\n", "\n", " sphinx-autobuild \n", "\n", "This will start a local webserver which will serve the generated HTML pages at http://localhost:8000/.\n", "Whenever you save changes in one of your notebooks, the appropriate HTML page(s) will be re-built and when finished, your browser view will be refreshed automatically.\n", "Neat!\n", "\n", "You can also abuse this to auto-build the LaTeX output:\n", "\n", " sphinx-autobuild -b latex\n", "\n", "However, to auto-build the final PDF file, you'll need an additional tool.\n", "Again, you can use `latexmk` for this (see [above](#Running-Sphinx)).\n", "Change to the build directory and run\n", "\n", " latexmk -pdf -pvc\n", "\n", "If your PDF viewer isn't opened because of LaTeX build errors, you can use the option `-f` to *force* creating a PDF file." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Automatic Creation of HTML and PDF output on readthedocs.org\n", "\n", "This is very easy!\n", "\n", "1. Create an account on https://readthedocs.org/ and add your Github/Bitbucket repository (or any publicly available Git/Subversion/Mercurial/Bazaar repository).\n", "\n", "1. Create a file named [requirements.txt](requirements.txt) (or whatever name you wish) in your repository containing the required pip packages:\n", "\n", " nbsphinx\n", " ipykernel\n", "\n", "1. In the \"Advanced Settings\" on readthedocs.org, specify your `requirements.txt` file (or however you called it) in the box labelled \"Requirements file\". Kinda obvious, isn't it?\n", "\n", "1. Still in the \"Advanced Settings\", make sure the right Python interpreter is chosen. This must be the same version (2.x or 3.x) as you were using in your notebooks!\n", "\n", "1. Make sure that in the \"Settings\" of your Github repository, under \"Webhooks & services\", \"ReadTheDocs\" is listed and activated in the \"Services\" section. If not, use \"Add service\".\n", " There is probably a similar thing for Bitbucket.\n", "\n", "1. Done!\n", "\n", "After that, 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." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## HTML Themes\n", "\n", "The `nbsphinx` extension does *not* provide its own theme, you can use any of the available themes or create a custom one, if you feel like it.\n", "\n", "The following links show how the `nbsphinx` input and output cells look like in different themes.\n", "\n", "### Sphinx's Built-In Themes\n", "\n", "http://nbsphinx.readthedocs.org/en/alabaster-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/pyramid-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/classic-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/bizstyle-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/haiku-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/traditional-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/agogo-theme/\n", "\n", "### 3rd-Party Themes\n", "\n", "http://nbsphinx.readthedocs.org/en/readthedocs-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/bootstrap-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/cloud-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/py3doc-enhanced-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/basicstrap-theme/\n", "\n", "http://nbsphinx.readthedocs.org/en/dotted-theme/" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.5.1+" } }, "nbformat": 4, "nbformat_minor": 1 }