Run a JupyterBook on local machine

[LydiaFrance]

Trying to run JupyterBook locally

[myyong]

These are the steps I took to run JupyterBook on my local machine.

1. First I created a conda environment conda create --name jupyter-book
2. I activated the environment conda activate jupyter-book
3. Since I have no pip, I used conda-forge to install jupyter-book. conda install -c conda-forge jupyter-book
4. Then I cloned the Turing way git clone https://github.com/alan-turing-institute/the-turing-way.git
5. Checked out a branch ux-proposal by doing git checkout ux-proposal
6. Found the book directory and made a copy of the Turing-Way book cp -R website exploreTags
7. Then I made a change to the welcome.md file inside exploreTags directory.
8. Finally I built the JupyterBook jb build exploreTags. It gave me:

   Or paste this line directly into your browser bar:
   file:///Users/myong/Documents/workspace/the-turing-way/book/exploreTags/_build/html/index.html

Pasting the line into my browser showed me:

[myyong]

It looks like if I have this: only_build_toc_files: true in the _config.yml file as described here, it only builds the items which are defined in the _toc.yml. For example when I reduced the items in the _toc.yml, Edited: The only_build_toc_files: true reference is now here.

# ===== Guide for Reproducible Research ========================================
  - file: reproducible-research/reproducible-research
    sections:
    - title: Overview
      file: reproducible-research/overview
      sections:
      - title: Definitions
        file: reproducible-research/overview/overview-definitions
      - title: Added Advantages
        file: reproducible-research/overview/overview-benefit
    - title: Open Research
      file: reproducible-research/open
      sections:
      - title: Open Data
        file: reproducible-research/open/open-data
      - title: Open Source Software
        file: reproducible-research/open/open-source

It only generates those items:

So @LydiaFrance if we pursue your idea of generating the table of contents based on tags, we have a second option to the sphinx-build -t xyz idea.

[myyong]

Or we can use this exclude_patterns: [pattern1/*, path/to/myfile.ipynb] as found here to exclude files, so we won't need to generate the entire TOC.

Putting the pattern exclude_patterns: [reproducible-research/open/*] in _config.yml results in this.

However, it is harder to debug and it is an exclusion pattern whereas we really want an inclusion pattern.

[myyong]

Noting there is a toggle to hide content here but I don't think that's what we want.

[LydiaFrance]

It looks like if I have this: only_build_toc_files: true in the _config.yml file as described here, it only builds the items which are defined in the _toc.yml.

@myyong We could look into generating the TOC using tags/metadata within the markdown files. That would make the workflow

write .md file -> add tags in the markdown file -> generate TOC only including certain tags -> generate the jupyter book from the TOC

I'm now looking into what adding tags into a markdown file could look like.

[myyong]

Is it my imagination or has the documentation for Jupyterbook changed?? The only_build_toc files reference is gone. Edited: It is now here

But it looks like we can generate a toc as described here using jupyter-book toc from-project path/to/book -f [jb-book/jb-article]. But it does that by searching contents, so we need to make it filter the content

[myyong]

So @LydiaFrance 's workflow in more detail

1. write .md file
2. add tags in the markdown file
3. generate TOC only including certain tags jupyter-book toc from-project path/to/book -f [jb-book/jb-article] + filter
4. generate the jupyter book from the TOC only_build_toc files:true in config.yml

[LydiaFrance]

To install jupterbook directly (not as a python package but from the source files)

1. git clone https://github.com/alan-turing-institute/jupyter-book Our own version of the jupter-book files
2. cd jupyter-book
3. pip install -e '.[all]' Make sure all the necessary packages are installed (note: the quotes are not included in the JupyterBook documentation)
4. jb build jupyter-book/book-template To build the example book
5. Paste the given html link to a browser to view the book.

[myyong]

Because pip hates me (mutual) here the conda alternative: conda install -c conda-forge jupyter-book