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 version#

You can either convert your ipynb files to earier to read locally or on GitHub.

The GitHub version means installing less locally, but means that after you push changes, you’ll need to pull the changes that GitHub makes.

To manage with a precommit hook jupytext conversion#

change your .pre-commit-config.yaml file to match the following:

repos:
-   repo: https://github.com/mwouts/jupytext
    rev: v1.10.0  # CURRENT_TAG/COMMIT_HASH
    hooks:
    - id: jupytext
      args: [--from, ipynb, --to, myst]

Run Precommit over all the files to actually apply that script to your repo.

pre-commit install
pre-commit run --all-files

If you do git status now, you should have a .md file for each ipynb file that was in your repository, now add and commit those.

Now, each time you commit, it will run jupytext first.

To manage with a gh action jupytext conversion#

create a file at .github/workflows/jupytext.yml and paste the following:

name: jupytext

# Only run this when the master branch changes
on:
  push:
    branches:
    - main
    # If your git repository has the Jupyter Book within some-subfolder next to
    # unrelated files, you can make this run only if a file within that specific
    # folder has been modified.
    #
    # paths:
    # - some-subfolder/**

# This job installs dependencies, build the book, and pushes it to `gh-pages`
jobs:
  jupytext:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2

    # Install dependencies
    - name: Set up Python 3.7
      uses: actions/setup-python@v1
      with:
        python-version: 3.7

    - name: Install dependencies
      run: |
        pip install jupytext
    - name: convert
      run: |
          jupytext */*.ipynb --to myst
          jupytext *.ipynb --to myst
    - uses: EndBug/add-and-commit@v4 # You can change this to use a specific version
      with:
        # The arguments for the `git add` command (see the paragraph below for more info)
        # Default: '.'
        add: '.'

        # The name of the user that will be displayed as the author of the commit
        # Default: author of the commit that triggered the run
        author_name: Your Name

        # The email of the user that will be displayed as the author of the commit
        # Default: author of the commit that triggered the run
        author_email: you@uri.edu

        # The local path to the directory where your repository is located. You should use actions/checkout first to set it up
        # Default: '.'
        cwd: '.'

        # Whether to use the --force option on `git add`, in order to bypass eventual gitignores
        # Default: false
        force: true

        # Whether to use the --signoff option on `git commit`
        # Default: false
        signoff: true

        # The message for the commit
        # Default: 'Commit from GitHub Actions'
        message: 'convert notebooks to md'

        # Name of the branch to use, if different from the one that triggered the workflow
        # Default: the branch that triggered the workflow (from GITHUB_REF)
        ref: 'main'

        # Name of the tag to add to the new commit (see the paragraph below for more info)
        # Default: ''
        tag: "v1.0.0"

      env:
        # This is necessary in order to push a commit to the repo
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Leave this line unchanged

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. Each chapter or file should have a descriptive file name (with_no_spaces) and descriptive title for it.

Syncing markdown and ipynb files#

If you have the precommit hook working, git will call a script and convert your notebook files from the ipynb format (which is json like) to Myst Markdown, which is more plain text with some header information. The markdown format works better with version control, largely because it doesn’t contain the outputs.

If you don’t get the precommit hook working, but you do get jupytext installed, you can set each file to sync.

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.

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.