Merge pull request #135 from choldgraf/build_update

Build update

MAINTAINING.md

@@ -0,0 +1,25 @@
+# The Jupyter Book maintainer's guide
+
+This is a short guide for maintaining Jupyter Book. If you're brand new to
+Jupyter Book, you should probably check out the [Contributing Guide](https://github.com/jupyter/jupyter-book/blob/master/CONTRIBUTING.md)
+first!
+
+## How is the documentation deployed?
+
+Jupyter Book deploys its documentation automatically using CircleCI. The
+documentation lives as a collection of HTML files on the `gh-pages` branch
+of the repository. CircleCI has the permissions to push to `gh-pages`, and
+so the following things happen to get the docs updated:
+
+When a PR is merged into master, do the following:
+
+1. First, run a Docker image with Python and use `jupyter-book` to build the
+   latest markdown files from the latest `content/` folder. ([circleci step here](https://github.com/jupyter/jupyter-book/blob/master/.circleci/config.yml#L65)).
+   Persist the contents of the `_build/` folder with the `persist_to_workspace` command.
+2. Then, run a Ruby image that loads in the `_build/` folder and builds the HTML
+   for the site using Jekyll. ([circleci step here](https://github.com/jupyter/jupyter-book/blob/master/.circleci/config.yml#L18)).
+3. Finally, `git push` the contents of `_site/` to the `gh-pages` branch of the
+   repository, including a `.nojekyll` folder, and then GitHub Pages will host
+   the updated site.
+
+All of this is [configured in the CircleCI configuration](https://github.com/jupyter/jupyter-book/blob/master/.circleci/config.yml).

jupyter_book/book_template/_build/03/1/Expressions.md

@@ -46,17 +46,18 @@ The grammar rules of a programming language are rigid. In Python, the `*` symbol
 ```
 
 
-
 {:.output .output_traceback_line}
 ```
-  File "<ipython-input-4-d90564f70db7>", line 1
-    3 * * 4
-        ^
-SyntaxError: invalid syntax
 
-```
+      File "<ipython-input-4-d90564f70db7>", line 1
+        3 * * 4
+            ^
+    SyntaxError: invalid syntax
+
 
 
+```
+
 Small changes to an expression can change its meaning entirely. Below, the space between the `*`'s has been removed. Because `**` appears between two numerical expressions, the expression is a well-formed *exponentiation* expression (the first number raised to the power of the second: 3 times 3 times 3 times 3). The symbols `*` and `**` are called *operators*, and the values they combine are called *operands*.
 
 

jupyter_book/book_template/_build/guide/03_build.md

@@ -42,7 +42,7 @@ than the timestamp of the corresponding file in your `content/` folder.
 
 From here, you have **two options**
 
-1. **Option 1: Jekyll builds the site for you**:
+1. **Option 1: GitHub builds the site for you**:
 
    By default, pushing a repository
    cloned from Jupyter Book will tell GitHub to use Jekyll to build the repository
@@ -54,18 +54,89 @@ From here, you have **two options**
 
    Building your book's site locally lets you preview your book locally before you
    push it online. It also gives you a bit more functionality than using
-   GitHub Pages to build your book. However, it also requires you to install Ruby.
+   GitHub Pages to build your book. However, it also requires you to install
+   Docker or Singularity (containerization platforms) _or_
+   Ruby (an open source programming language).
    If you'd like to build your site locally then jump to the next section.
 
-## Build the book's site HTML locally (optional)
+## Build the book's site HTML locally
 
-If you'd like to build your book's site HTML locally, you'll need to first
-install the necessary dependencies and then build the HTML. Follow these
-steps to do so.
+Once you've generated the markdown for your notebooks and installed the
+necessary dependencies. You are ready to build your site HTML.
+
+Ensure that your notebooks have been converted to markdown, there should be a
+collection of them in `_build/`.
+
+In order to locally build your site's HTML with Jekyll, you'll need to either install
+a container software (Docker or Singularity) or Ruby.
+
+In our experience, we've found that [containers](https://www.docker.com/resources/what-container)
+provide an easier installation for most systems.
+If you are developing on a system where you have administrator privileges
+(i.e., you have `root` permissions), we recommend you use [Docker](https://docs.docker.com/get-started/).
+
+We also provide instructions for using [Singularity](https://www.sylabs.io/guides/2.6/user-guide/quick_start.html),
+an alternate containerization software for systems where you do not have administrator privileges.
+To learn more about using containers, please see the
+[Docker for scientists guide](https://neurohackweek.github.io/docker-for-scientists/).
+
+### Building your site locally with Containers: Docker
+
+First, you'll need to make sure you have Docker installed.
+There are [installation instructions for each operating system](https://hub.docker.com/search/?type=edition&offering=community)
+to guide you through this process.
+
+Once Docker is available on your system, you can build the image locally with:
+
+```bash
+docker pull emdupre/jupyter-book
+```
+
+You can then access this image with:
+
+```bash
+docker run --rm --security-opt label:disable  \
+   -v /full/path/to/your/book:/srv/jekyll \
+   -p 4000:4000 \
+   -it -u 1000:1000 \
+   emdupre/jupyter-book bundle exec jekyll serve --host 0.0.0.0
+```
+
+If you navigate to `http://0.0.0.0:4000/jupyter-book/` in your browser,
+you should see a preview copy of your book.
+If you instead see an error, please try to update your local book;
+see [the Jupyter Book FAQ section](https://jupyter.org/jupyter-book/guide/04_faq.html#how-can-i-update-my-book)
+for more details on how to do so.
 
-### Install the dependencies to preview your book locally
+### Building your site locally with Containers: Singularity
 
-You'll need Ruby, an open-source programming language, to build your site's
+If you are on a system where you do not have administrator privileges (such as a shared
+computing cluster), you will not be able to use Docker.
+Instead, you can use Singularity.
+First, you'll need to check with your resource manager that Singularity is available
+on your system.
+
+You can then create a Jupyter Book Singularity image using:
+
+```bash
+singularity build jupyter-book.simg docker://emdupre/jupyter-book
+```
+
+Next, you can access this image with:
+
+```bash
+singularity run -B /full/path/to/your/book:/srv/jekyll \
+    --pwd /srv/jekyll \
+    jupyter-book.simg bundle exec jekyll serve
+```
+
+And that's it! If you navigate to `http://127.0.0.1:4000/jupyter-book/` in your browser,
+you should see a preview copy of your book.
+
+### Building your site locally with Ruby
+
+You can also choose to build your site locally without a container.
+In this case, you'll need Ruby, an open-source programming language, to build your site's
 HTML with Jekyll. The easiest way to install Ruby on *nix systems is to use
 the *`conda`* package manager:
 
@@ -78,19 +149,10 @@ Once you have Ruby installed, run
 make install
 ```
 
-which will install Bundler (a Ruby depency management tool) and then install the plugins
+which will install Bundler (a Ruby dependency management tool) and then install the plugins
 needed to build the site for your book.
 
-### Build the site HTML for your book
-
-Once you've generated the markdown for your notebooks and installed the
-necessary dependencies. You are ready to build your site HTML.
-
-Ensure that your notebooks have been converted to markdown, there should be a
-collection of them in `_build/`.
-
-Once you've confirmed this, run this command to generate your book's HTML using
-Jekyll:
+You can then build the site locally by running:
 
 ```
 make site

jupyter_book/book_template/_build/guide/04_faq.md

@@ -42,6 +42,14 @@ jupyter-book create -h
 You should check out the content in your upgraded book to make sure it looks correct, then
 commit the changes to your repository.
 
+## Does the book behave differently depending on the browser?
+
+Maybe - Jupyter Book does use some features that might have different behaviors in
+some browsers. For example, Safari [tends to treat downloadable objects](https://github.com/jupyter/jupyter-book/pull/104#issuecomment-462461188)
+differently for some reason.
+
+The two browsers on which Jupyter Book should always behave as expected are
+**Firefox** and **Chrome**.
 
 ## Why isn't my math showing up properly?
 
@@ -58,7 +66,7 @@ be included in this script, please open an issue
 
 ## How can I include interactive Plotly figures?
 
-To display interactive [Plotly](https://plot.ly/python/) figures, they must 
+To display interactive [Plotly](https://plot.ly/python/) figures, they must
 first be generated in a Jupyter notebook using the [offline mode](https://plot.ly/python/offline/).
 You must then plot the figure with `plotly.offline.plot()`, which generates an HTML file (`plotly.offline.iplot()` does not),
 and then load the HTML into the notebook with `display(HTML('file.html'))` prior to saving your *.ipynb file.

jupyter_book/book_template/_build/guide/05_advanced.md

@@ -44,6 +44,26 @@ In both cases, the cells *will* remain in the notebooks themselves, they
 simply won't show up in the site's HTML, so links that point to a JupyterHub/
 Binder/etc will still work as expected.
 
+## Enable Google Analytics
+
+If you have a Google Account, you can use Google Analytics to collect some 
+information on the traffic to your Jupyter Book. With this tool, you can find 
+out how many people are using your site, where they come from and how they 
+access it, wether they are using the Desktop or the mobile version etc. 
+
+To add Google Analytics to your Jupyter Book, navigate to 
+[Google Analytics](https://analytics.google.com/analytics/web/), create a new 
+Google Analytics account and add the url of your Jupyter Book to a new 
+*property*. Once you have set everything up, your Google Analytics property 
+will have a so-called Tracking-ID, that typically starts with the letters UA. 
+All that you need to do is to copy this ID and paste it into your 
+configuration file:
+
+```yaml
+google_analytics:
+  mytrackingcode: UA-XXXXXXXXX-X
+```
+
 ## Retain custom YAML front-matter in your files
 
 Jupyter book will check your files for YAML front-matter and will **append**