Formatting Tips#
Warning
This is all based on you having accepted the portfolio assignment on github and having a cloned copy of the template. If you are not enrolled or the initial assignment has not been issued, you can view the template on GitHub
Your portfolio is a jupyter book. This means a few things:
it uses myst markdown
it will run and compile Jupyter notebooks
This page will cover a few basic tips.
Managing Files and versions#
Important
This will be updated; new githut features change how it works
Organization#
The summary of for the part
or whole submission, should match the skills to the chapters. Which prompt you’re addressing is not important, the prompts are a starting point not the end goal of your portfolio.
Data Files#
Also note that for your portfolio to build, you will have to:
include the data files in the repository and use a relative path OR
load via url
using a full local path(eg that starts with ///file:
) will not work and will render your portfolio unreadable.
Structure of plain markdown#
Use a heading like this:
# Heading of page
## Heading 2
### Heading 3
in the file and it will appear in the sidebar.
You can also make text italic or bold with either *asterics*
or __underscores__
with _one for italic_
or **two for bold**
in either case
File Naming#
It is best practice to name files without spaces, underscores _
or hyphens -
are both good.
Each chapter
or file should have a descriptive file name (with_no_spaces
) and descriptive title for it.
Adding annotations with formatting or margin notes#
You can either install jupytext and convert locally or upload /push a notebook to your repository and let GitHub convert.
Then edit the .md file with a text editor of your choice. You can run by uploading if you don’t have jupytext installed, or locally if you have installed jupytext or jupyterbook.
In your .md file use backticks to mark special content blocks
```{note}
Here is a note!
```
```{warning}
Here is a warning!
```
```{tip}
Here is a tip!
```
```{margin}
Here is a margin note!
```
For a complete list of options, see the sphinx-book-theme
documentation.
Links#
Markdown syntax for links
[text to show](path/or/url)
Configurations#
Things like the menus and links at the top are controlled as settings, in _config.yml
. The following are some things that you might change in your configuration file.
Show errors and continue#
To show errors and continue running the rest, add the following to your configuration file:
# Execution settings
execute:
allow_errors : true
Using additional packages#
You’ll have to add any additional packages you use (beyond pandas and seaborn) to the requirements.txt
file in your portfolio.