Skip to content

Latest commit

 

History

History
117 lines (68 loc) · 5.06 KB

README.md

File metadata and controls

117 lines (68 loc) · 5.06 KB

Notebook pub template

This repo is a template for notebook publications. The publication rendered and hosted by this repository serves as a demo that can be viewed at this URL.

How to use this template

  1. Create a repo from this template

    In the top-right of this GitHub repo, select the green button that says "Use this template".

    IMPORTANT: When creating your repo from this template, you need to check the box that says, "Include all branches"

  2. Config edits

    • Replace the variables in _variables.yml
      • For google_analytics, provide the publishing team your repo name and they'll provide you a Google Analytics tracking ID.
    • Replace the variables in authors.yml.
      • This can always be updated, but for now at least add yourself.

  3. Install Quarto

    The publication is rendered with Quarto. If you don’t have it installed (check with quarto --version), you can install it here.

  4. Setup the code environment

    This repository uses conda to manage the computational and build environment. If you don’t have it installed (check with conda --version), you can find operating system-specific instructions for installing miniconda here.

    When you're ready, run the following commands to create and activate the environment. Replace [REPO-NAME] with your repository name.

    conda env create -n [REPO-NAME] --file env.yml
conda activate [REPO-NAME]

    (As you introduce dependencies to your publication, or if you already have your full set of dependencies, add them to env.yml with the version pinned.)

    Now, install any internal packages in the repository:

    pip install -e .

    And finally, install the pre-commit hooks:

    pre-commit install

    Test your installation with make preview. Your pub will open up in your browser.

    Afterwards, create a branch to work on (don't commit to main directly).

  5. Create your pub

    Edit index.ipynb to create your pub. As you work, render it in a live preview with make preview.

How to publish

Publishing is handled automatically with a GitHub Action that triggers whenever a pull request is merged into publish. Thus, all the following action items should be completed before your pull request is approved and subsequently merged.

  1. Enable read/write permissions for GitHub Actions

    In your repo, go to Settings -> Actions -> General -> Workflow permissions, and check the box, "Read and write permissions"

  2. Populate the README_TEMPLATE.md

    Populate README_TEMPLATE.md and then rename it to README.md.

    NOTE: The content you're reading now is the current README.md, which is to be replaced with README_TEMPLATE.md.

  3. Remove placeholder package

    If you did not populate src/analysis with your own content, remove it (rm -rf src/analysis).

  4. Remove reference to the syntax demo from _quarto.yml

    Feel free to keep demo.ipynb in your repo, but remove the following lines in _quarto.yml:

    - text: 'Demo'
  href: demo.ipynb

    This will remove Demo from the navigation bar.

  5. Make the repository public

    In order for this pub to be open and reproducible, make the repo public.

  6. Enable comments

    Comments are handled with Giscus, which Quarto has an integration for. Once enabled, a widget is placed at the bottom of the publication that provides an interface to read, write, react, and respond to GitHub Discussions comments. Comments made through the interface are automatically added as comments to a GitHub Discussions thread of your repository.

    First, enable GitHub Discussions for your repo.

    Second, install the Giscus App for your repository. Click Configure, select Arcadia-Science, then select your repository from the dropdown. Click Update access.

    IMPORTANT: Do not deselect any of the other Arcadia-Science repositories that already have the Giscus app installed, e.g. Arcadia-Science/notebook-pub-template.

    Now, edit the comments section in _quarto.yml with your repo name:

    comments:
  giscus:
    repo: Arcadia-Science/notebook-pub-template
    input-position: top

    You may have to wait a few minutes for make preview to properly render the Giscus widget.

  7. Final checks

    Complete the steps in the section, "Final checks" in CONTRIBUTING.qmd.

Publishing revisions

See CONTRIBUTING.qmd.