<jupyter_start><jupyter_text>*Creating a Jupyter Book with The Turing Way* Module 4: Configuring your Jupyter Book**Learning Objective:**   - Explain how we can personalise the appearance of our Jupyter Book  - Explain what a `_config.yml` file is and what display parameters of our Jupyter Book can be manipulated using it  - Guide our learners to link the contents of Jupyter Book with its GitHub repository online       📹 [VIDEO](TBA)---  Configuring your book So far we have created a Jupyter Book that looks very basic. It doesn't even have a logo or a title!As you probably have guessed, we are using the [default configuration](https://jupyterbook.org/customize/config.htmlconfiguration-defaults) of Jupyter Book. To adapt it to our needs, we need to create a `_config.yml` file and fill it with our desired parameters. We will start by setting the title and logo of our Jupyter Book, which will appear in the left navigation bar. We will also define relevant information that will appear on the footer of the main page:<jupyter_code>from ruamel.yaml import YAML

config_document_1 = """
title                       : The Turing Way  # The title of the book
author                      : The Turing Way Community  # The author of the book to be placed in the footer
copyright                   : "2020"  # Copyright year to be placed in the footer
logo                        : "./figures/logo.png"  # A path to the book logo

"""

# Save our _config.yml in the book path
yaml = YAML()
config_file = open('../book_module4/_config.yml', 'w')
yaml.dump(yaml.load(config_document_1), config_file)<jupyter_output><empty_output><jupyter_text>Let's build our Jupyter Book again to see the effects of our `_config.yml`. In this module we are going to build our book based on the folder `book_module4` in our main repository that already contains the content files and a `_toc.yml`:<jupyter_code>!jupyter-book build ../book_module4/<jupyter_output><empty_output><jupyter_text>EXERCISETry changing the author of the Jupyter Book and its logo. Modify the `_config.yml` to do so, and re-build your book.__Answer:__ Print an example of a modified configuration file by running the command below.<jupyter_code>!cat ../answers/module_4/ex1.yml<jupyter_output><empty_output><jupyter_text>Further display settings We can further change other elements of the appearance of our Jupyter Book. For example, let's add a [favicon](https://en.wikipedia.org/wiki/Favicon) to our book, and add some additional text to the footer in the navigation bar:<jupyter_code>config_document_2 = config_document_1 + """
html:
  favicon                   : "./figures/favicon-32x32.png"  # A path to a favicon image
  navbar_footer_text        :
    'Visit our <a href="https://github.com/alan-turing-institute/the-turing-way">GitHub Repository</a>
    <div>
    This book is powered by <a href="https://jupyterbook.org">Jupyter Book</a>
    </div>'  # Will be displayed underneath the left navigation bar.

"""

# Save our _config.yml in the book path
yaml = YAML()
config_file = open('../book_module4/_config.yml', 'w')
yaml.dump(yaml.load(config_document_2), config_file)
!jupyter-book build ../book_module4/<jupyter_output><empty_output><jupyter_text>EXERCISEWe actually don't want to show the `welcome page` in our navigation bar. Read the [official documentation](https://jupyterbook.org/customize/config.htmlconfiguration-defaults) to figure out how to change this parameter, and re-build your Jupyter Book.__Answer:__ Run the command below to see an example of a configuration file that achieves this.<jupyter_code>!cat ../answers/module_4/ex2.yml<jupyter_output><empty_output><jupyter_text>Linking the contents of Jupyter Book with its GitHub repository If our book is hosted on [GitHub](https://github.com/), we can link our Jupyter Book with our repository using a custom button at the top of the main page. Take [The Turing Way](https://the-turing-way.netlify.app/welcome) as an example:![github_button](./images/github-button-turing.png)Notice that we don't have this button in our Jupyter Book yet.The same button (but a different option in its dropdown menu) can also give our readers a direct link to open an issue about some specific content of our Jupyter Book.Let's add these two options to our Jupyter Book by adding the following to our `_config.yml`:<jupyter_code>config_document_3 = config_document_2 + """
  use_repository_button     : true  # Whether to add a link to your repository button
  use_issues_button         : true  # Whether to add an "open an issue" button

"""

# Save our _config.yml in the book path
yaml = YAML()
config_file = open('../book_module4/_config.yml', 'w')
yaml.dump(yaml.load(config_document_3), config_file)
!jupyter-book build ../book_module4/<jupyter_output><empty_output><jupyter_text>Our Jupyter Book could not be built! We asked Jupyter Book to link our content to our GitHub repository, but we haven't specified the repository. Let's add this:<jupyter_code>config_document_4 = config_document_3 + """
repository:
  url                       : https://github.com/alan-turing-institute/the-turing-way  # The URL to your book's repository
  path_to_book              : "book/website"  # A path to your book's folder, relative to the repository root
  branch                    : master  # Which branch of the repository should be used when creating links

"""

# Save our _config.yml in the book path
yaml = YAML()
config_file = open('../book_module4/_config.yml', 'w')
yaml.dump(yaml.load(config_document_4), config_file)
!jupyter-book build ../book_module4/<jupyter_output><empty_output>
StarcoderdataJupyterStructuredCleanDedup