notebooks/7-final-demo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Creating a Jupyter Book with The Turing Way*\n",
    "\n",
    "# Module 7: Demo of Jupyter Book features in _The Turing Way_\n",
    "\n",
    "**Learning Objective:**\n",
    "  - Explain Sphinx features in Jupyter Book for referencing resources and create a bibliography for the book\n",
    "  - Show how one can cross reference chapters and sections within the book\n",
    "  - Show how to use figures in the chapters that can be cross references\n",
    "  - Demo the collaborative workflow to read, edit and export files directly from the chapters\n",
    "  <!---for cross-referencing, citation, pdf export, collaborative workflow on GitHub repository to edit a chapter or propose edits on Jupyter Book--->\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Citing and Referencing\n",
    "\n",
    "Jupyter Book uses a centralised bibtex file containing all references.\n",
    "In this tutorial, we have provided you with a `references.bib`, which contains all the citations used in the `Overview` chapter. You can open this file in Jupyter Notebook to inspect the different entries.\n",
    "\n",
    "It's crucial that this bibtex file is located within the folder where you store all the components for you Jupyter Book.\n",
    "A complete version of this file for _The Turing Way_ can be found [here](https://github.com/alan-turing-institute/the-turing-way/blob/master/book/website/_bibliography/references.bib)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding a new reference in `references.bib`\n",
    "\n",
    "You can edit references locally by editing `references.bib` directly using a text editor (or in Jupyter Notebook for this tutorial).\n",
    "There are many online tools and browser plugins that allow exporting references in bibtex format. \n",
    "For example, see [ZoteroBib](https://zbib.org/) that takes a URL or DOI as input and allows exporting the reference in bibtex format (including many others).\n",
    "The browser extensions like [BibItNow!](https://addons.mozilla.org/en-GB/firefox/addon/bibitnow/) in Firefox and [BibTeX entry from URL](https://chrome.google.com/webstore/detail/bibtex-entry-from-ur) in chrome are also useful for copying the reference for online materials.\n",
    "\n",
    "Bibligraphy managing program such as JabRef (linux, windows, macOS) or BibDesk (macOS) can also be used for editing `references.bib` directly.\n",
    "\n",
    "For example, in the `Overview` chapter in *The Turing Way*, and in your example book, we cite [Reproducibility crisis?, Baker, M., Nature, 533(26):353–66, 2016](https://www.icts.uci.edu/education/ffast1/nature.pdf).\n",
    "\n",
    "Entry for this citation in bibtex is the follwing (look up the first entry in the `references.bib` file):\n",
    "\n",
    "```\n",
    "@article{baker2016reproducibility,\n",
    "    author={Baker, Monya},\n",
    "  \ttitle={Reproducibility crisis?},\n",
    "  \tjournal={Nature},\n",
    "  \tvolume={533},\n",
    "  \tnumber={26},\n",
    "  \tpages={353--66},\n",
    "  \tyear={2016}}\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding a citation\n",
    "\n",
    "To include a citation in your content, we follow the recommendation by Jupyter Book that is built on top of [Sphinx](https://jupyterbook.org/reference/glossary.html#term-Sphinx).\n",
    "\n",
    "To include a reference using ``{cite}`CITEKEY` ``, where `CITEKEY` is the corresponding citation key in `references.bib`.\n",
    "\n",
    "We will cite the article that we used in the previous section as an example, so CITEKEY will correspond to `baker2016reproducibility`.\n",
    "\n",
    "We can link this citation by adding the following syntax to the content:\n",
    "```\n",
    "{cite}`baker2016reproducibility`\n",
    "```\n",
    "This citation will appear in your chapter as `[bak16]`.\n",
    "\n",
    "You can also give an alternative title like so:\n",
    "```\n",
    "{cite}`M. Baker (2016)<baker2016reproducibility>`\n",
    "```\n",
    "The citation will now appear in your chapter as `M. Baker (2016)`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Creating a bibliography chapter in Jupyter Book\n",
    "\n",
    "Let's add the entire bibliography of our book as a separate chapter of Jupyter Book.\n",
    "When we cite a resource, a link is created with the citation, which can be clicked to see the details.\n",
    "In *The Turing Way*, those links will direct our readers to the [bibliography](https://the-turing-way.netlify.app/afterword/bibliography.html) page, which we have not included in this tutorial.\n",
    "\n",
    "___EXERCISE:___\n",
    "\n",
    "For this module we will be using the contents of the Jupyter Book that were used for module 6, that is, we will be building our book based on the folder named `book_module6`. \n",
    "\n",
    "To create a bibliography page, we have provided `bibliography.md` file in the `content` folder. To include it in your Jupyter Book, first copy the file over to the `book_module6` folder, and inspect its content."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!cp ../content/bibliography.md ../book_module6/bibliography.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's print the content of `bibliography.md`: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cat ../book_module6/bibliography.md"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above syntax will generate a bibliography with all the references in your bibtex file."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Edit your `_toc.yml` file manually by appending `bibliography.md` as a separate chapter:\n",
    "\n",
    "```\n",
    "- file: bibliography\n",
    "  title: Bibliography\n",
    "```\n",
    "And, rebuild your book:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!jupyter-book build ../book_module6/"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check your Jupyter Book, the bibliography chapter should have been included.\n",
    "\n",
    "You should also see some warnings on the build. Sphinx is complaining that the same citation keys are used multiple times, which makes sense since we are citing the same references over multiple chapters. If you want to avoid this warning, your could use another style for citing your references. Read how to achieve this in the [official documentation](https://jupyterbook.org/content/citations.html#selecting-your-reference-style).\n",
    "\n",
    "For more advanced usage, see the the documentation by [sphinxcontrib-bibtex extension](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/), which is a Sphinx extension for BibTeX style citations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Cross-Referencing Sections and Chapters\n",
    "\n",
    "In Jupyter Book, labels are a way to add tags to parts of your content or a file that you can reference later on. \n",
    "This is very helpful because you can insert labels to other parts of your book without worrying about the relative or absolute paths of the file.\n",
    "\n",
    "To add a label for a section in a chapter/subchapter, we use a syntax of the following pattern before the element you wish to reference:\n",
    "\n",
    "```\n",
    "(my-label-name)=\n",
    "# The thing that I want to label\n",
    "```\n",
    "\n",
    "You can insert cross-references to the labels of sections in your file with the following syntax:\n",
    "\n",
    "```\n",
    "{ref}`my-label-name`\n",
    "\n",
    "```\n",
    "\n",
    "Such labels can be used on the top of the headers for cross referencing chapters or sections (top header for the chapter, and lower level headers for sections).\n",
    "\n",
    "For this tutorial, labels for each file in the `Overview` chapters have been created for the top headers.\n",
    "For example, see the `overview.md` file in the `content/overview` folder, where a label `rr-overview` has been created by adding `(rr-overview)=` before the top header is given.\n",
    "\n",
    "**Note**: Here, \"rr\" is used as an abbreviation for Reproducible Research, and \"overview\" is the chapter name.\n",
    "However, there is not hard guideline for what names can be used for creating such labels.\n",
    "\n",
    "Other subchapters have similar labels named: `rr-overview-definitions`, `rr-overview-benefits` and `rr-overview-resources`.\n",
    "\n",
    "To cross reference one of these labels, for example `rr-overview-definitions`, we will add the following syntax where we want to refer to this subchapter: \n",
    "\n",
    "```\n",
    "{ref}`definitions <rr-overview-definitions>`\n",
    "```\n",
    "\n",
    "See the first sentence of the `overview.md` file, where this cross referencing has been made.\n",
    "\n",
    "For more examples, and to see the style guide used in *The Turing Way*, please read this [chapter](https://the-turing-way.netlify.app/community-handbook/style/style-crossref.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Figures\n",
    "\n",
    "The current version of Jupyter Book supports Markedly Structured Text (MyST) as discussed in [Module 5](./5-more-jupyterbook.ipynb).\n",
    "\n",
    "All the figures used in a Jupyter Book should also be placed in the same folder where all important components of the books are stored.\n",
    "In this tutorial, we have provided the `figures` folder where all the images used in the example Jupyter Book are stored.\n",
    "\n",
    "To include a figure in a chapter, for example [reproducibility.jpg](./figures/reproducibility.jpg) file, use this pattern:\n",
    "\n",
    "```\n",
    "```{figure} ./figures/reproducibility.jpg\n",
    "---\n",
    "height: 500px\n",
    "name: reproducible-path\n",
    "alt: A person showing another person what steps to take to make your data research reproducible.\n",
    "---\n",
    "_The Turing Way_ project illustration by Scriberia. Zenodo. [http://doi.org/10.5281/zenodo.3332807](http://doi.org/10.5281/zenodo.3332807).```\n",
    "\n",
    "```\n",
    "\n",
    "Here, values for \"height:\" specify the preferred height of the figure (in this case it is 500 pixels), \"name:\" specifies a key (like label) for this figure and \"alt:\" specifies an alternative text (so that a screen reader app can explain the image correctly).\n",
    "\n",
    "This way of including a figure also allows cross referencing to it in other chapters as shown in the section above.\n",
    "\n",
    "The example figure can be referred in other files using the {ref} role like so: \n",
    "```\n",
    "{ref}`reproducible-path`\n",
    "```\n",
    "\n",
    "For more advanced parameters, please see the [Jupyter Book Documentation](https://jupyterbook.org/content/figures.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Collaborative workflow \n",
    "\n",
    "<img src=\"../images/theturingway-navigation-jc2020.png\" />\n",
    "\n",
    "*Jupyter Book feature makes _The Turing Way_ navigable and collaborative.*\n",
    "\n",
    "As discussed in [Module 1](./1-welcome.ipynb), users of Jupyter Book can read the chapters online by navigating its content easily through its table of contents (highlighted in the image as **1** and **5**).\n",
    "\n",
    "Users of this book can also edit the Markdown file or open an issue to report suggestions or error (highlighted in the image as **3**).\n",
    "This configuration can be edited in the `_config.yml` file (that you saw in [Module 5](./5-more-jupyterbook.ipynb)).\n",
    "You can see the [_config.yml file](https://github.com/alan-turing-institute/the-turing-way/blob/master/book/website/_config.yml) of *The Turing Way* as an example.\n",
    "\n",
    "Chapters and subchapters of the Jupyter Book can be downloaded as pdf or Markdown format so that users can read the book offline (highlighted in the image as **4**).\n",
    "\n",
    "To learn about more advanced features of Jupyter Book, please read the following sections in the official documentation: [MAKE YOUR BOOK INTERACTIVE](https://jupyterbook.org/interactive/launchbuttons.html#) and [ADVANCED AND MISCELLANEOUS](https://jupyterbook.org/advanced/pdf.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "## Takeaway\n",
    "---\n",
    "\n",
    "- In this module, using examples from *The Turing Way*, we discussed useful features that provides easy navigation and collaboration in Jupyter Book.\n",
    "- We can add bibtex citation of external resources in the `references.bib`, and cite them in the book chapters using the ``{cite}`CITEKEY` ``, where CITEKEY is the corresponding citation key in references.bib.\n",
    "- We can create labels for different headers or chapters, subchapters and sections in each file (using `(label-name)=`) to cross reference them in the different chapters within the book (using ``{ref}`label-name` ``).\n",
    "- Jupyter Book provides a collaborative interface for users to contribute to the book by using its GitHub integration to read a chapter online and suggest edits to those by visiting them on its GitHub repository.\n",
    "- There are many advanced features that make Jupyter Book an appropriate tool for *The Turing Way* to maintain and develop its resources in a community-led and collaborative manner.\n",
    "  \n",
    "\n",
    "### References\n",
    "\n",
    "**Jupyter Book**\n",
    "\n",
    "- [GitHub](https://github.com/executablebooks/jupyter-book)\n",
    "- [Contribution guideline](https://jupyterbook.org/contribute/intro.html)\n",
    "\n",
    "**The Turing Way**\n",
    "\n",
    "- [GitHub](https://github.com/alan-turing-institute/the-turing-way)\n",
    "- [Contribution guideline](https://github.com/alan-turing-institute/the-turing-way/blob/master/CONTRIBUTING.md)\n",
    "\n",
    "*Community resources*\n",
    "\n",
    "- [Code of Conduct](https://github.com/alan-turing-institute/the-turing-way/blob/master/CODE_OF_CONDUCT.md)\n",
    "- [Contribution guideline](https://github.com/alan-turing-institute/the-turing-way/blob/master/CONTRIBUTING.md)\n",
    "- [Monthly Newsletter](https://tinyletter.com/TuringWay/) \n",
    "- [Twitter @turingway](https://twitter.com/turingway)\n",
    "- [Join Slack channel](https://tinyurl.com/jointuringwayslack)\n",
    "- [Public Gitter](https://gitter.im/alan-turing-institute/the-turing-way)\n",
    "\n",
    "**Contact by email: [theturingway@gmail.com](mailto:theturingway@gmail.com)**\n",
    "\n",
    "***See [Frequently Asked Questions](https://github.com/alan-turing-institute/the-turing-way/blob/master/communications/promotion-pack/faqs.md) for supporting information***\n"
   ]
  }
 ],
 "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.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}