Merge pull request jupyter-book#101 from ExecutableBookProject/numbering

updating netlify docs and numbering docs

.github/workflows/tests.yml

@@ -48,6 +48,7 @@ jobs:
 
     - name: Install Headless Chrome dependencies
       run: |
+        sudo apt-get update
         sudo apt-get install -yq $(cat .github/workflows/pyppeteer_reqs.txt)
 
 

docs/_config.yml

@@ -13,6 +13,7 @@ html:
   google_analytics_id: UA-52617120-7
   home_page_in_sidebar: false
 
+
 repository:
   url                       : https://github.com/ExecutableBookProject/cli
   path_to_book              : "docs"

docs/_toc.yml

@@ -5,7 +5,8 @@
 - file: start/build
 - file: start/publish
   sections:
-    - file: start/publish-gh-pages
+    - file: publish/gh-pages
+    - file: publish/netlify
 - file: start/cli
 - file: customize/config
 - file: customize/toc

docs/publish/netlify.md

@@ -0,0 +1,81 @@
+# Publish with Netlify
+
+[Netlify](https://www.netlify.com/) is a continuous deployment service that can
+**automatically build an updated copy of your Jupyter Book** as you push new content.
+It can be used across git clients including GitHub, GitLab, and Bitbucket.
+
+Although Netlify has both free and paid tiers, the build process is the same across both.
+Importantly, the free tier only allows for 100GB of bandwidth usage per month across all of your Netlify built projects.
+
+If your Jupyter Book will be used by a large audience, or if you're creating many Jupyter
+Books, you might want to consider registering for [a paid account](https://www.netlify.com/pricing/).
+
+In order to use Netlify, you'll need to [create an account](https://app.netlify.com/signup).
+Here, we'll walk through connecting your Jupyter Book to Netlify's continous deployment services using their UI.
+You can also check out their [documentation on continuous deployment](https://www.netlify.com/docs/continuous-deployment/).
+
+```{admonition} **Prerequisites**
+We assume that you have already [built your book's HTML](../start/build) and that
+your HTML content is in the `_build/html` folder. We also assume that you have followed
+the instructions in {ref}`publish/online-repo`.
+```
+
+## Step 1: The Netlify site builder
+
+After you've created a Netlify account, you'll need to log in.
+The home page will be a dashboard of all sites you're currently building with Netlify.
+We can then import a new site by clicking the "New Site from Git" button in the upper right.
+
+This should launch [the site builder](https://app.netlify.com/start):
+
+![Netlify site builder](https://miro.medium.com/max/3413/1*pV0iG0v_6N00_YC07gP7qA.png)
+
+Here, you can select the git client where your Jupyter Book is hosted.
+For the purposes of this tutorial, we'll assume that your book is hosted on GitHub.
+
+When you select the "GitHub" option, you'll be asked to grant permission for Netlify to access your GitHub account.
+Authorizing access will take you to the next step of the build process, where you can select your Jupyter Book repository.
+
+![Netlify continous deployment](../images/netlify-cd.png)
+
+```{sidebar}
+If your book content is not in the root of your repository, make sure you point to it
+in the `jupyter-book build` command.
+```
+
+Once you've selected the correct repository, you'll need to supply build instructions.
+That is, the Netlify *Build command* should be `jupyter-book build .`
+and the *Publish directory* should be `_build/html`.
+
+You'll also need to select the appropriate branch to build your repository from.
+In this example, we'll use the `master` branch.
+
+![Netlify build command](../images/netlify-build.png)
+
+```{warning}
+**Note**: The default python environment is python 2.7,
+which means that some packages may fail to install.
+You can update the python environment by supplying a `runtime.txt` file,
+as detailed in [the Netlify documentation](https://www.netlify.com/docs/build-settings/#build-environment-variables).
+For a full list of available environments,
+please see the [Netlify build image details](https://github.com/netlify/build-image/blob/xenial/included_software.md#languages).
+```
+
+You can then select *Deploy site* and wait for the site to build.
+You'll be re-directed to the site dashboard during the build process.
+
+## Step 2: Updating your domain name
+
+If your site has successfully built, it will be assigned a random domain name.
+In order to have a more memorable address, you can update your site's name.
+
+From the site dashboard, select *Domain settings*.
+This will take you to a sub-menu, where you can choose to update your site name.
+
+![Netlify configure domain](../images/netlify-domain.png)
+
+You can enter a memorable, unique name here to describe your Jupyter Book!
+Note that it will be prepended to `.netlify.com` so, `MY-BOOK` will become `MY-BOOK.netlify.com`.
+
+You can also use a custom domain (i.e., one that you have purchased through a DNS registrar).
+See the [Netlify documentation on custom domains](https://www.netlify.com/docs/custom-domains/) for more details on this process.

docs/start/publish.md

@@ -13,6 +13,7 @@ Ensure that your the HTML has been built for each page of your book
 files in your book's `_build/html` folder.
 ```
 
+(publish/online-repo)=
 ## Create an *online* repository for your book
 
 Regardless of the approach you use for publishing your book online, it will require

jupyter_book/default_config.yml

@@ -16,6 +16,7 @@ execute_notebooks           : auto  # Whether to execute notebooks at build time
 # HTML-specific settings
 html:
   favicon                   : ""  # A path to a favicon image
+  sidebar_number_sections   : False  # Add a number to each section in your left sidebar
   sidebar_footer_text       : 'Powered by <a href="https://jupyterbook.org">Jupyter Book</a>'  # Will be displayed underneath the sidebar.
   google_analytics_id       : ""  # A GA id that can be used to track book views.
   home_page_in_sidebar      : true  # Whether to include your home page in the left Table of Contents

jupyter_book/yaml.py

@@ -71,6 +71,7 @@ def yaml_to_sphinx(yaml, config):
         sphinx_config["google_analytics_id"] = html.get("google_analytics_id")
 
         theme_options["sidebar_footer_text"] = html.get("sidebar_footer_text")
+        theme_options["number_toc_sections"] = html.get("sidebar_number_sections")
         theme_options["home_page_in_toc"] = html.get("home_page_in_sidebar")
 
     # Update the theme options in the main config