Guides, tutorials and OER

User Guide: Publication template

A Computational Publication Service (CPS) template - Demo #2

https://github.com/NFDI4Culture/cps-demo-2

Environment setup

1. Use the supplied CPS template to create a publication repository on GitHub
2. Loading the Git repository into a cloud development environment - a 2 core online computer, a Virtual Machine (VM) with an Integrated Development Environement (IDE)
3. Configure the Quarto publication rendering software
4. Run a Jupyter Notebook
5. Make a GitHub ‘commit and push’
6. Turn on the publication website on GitHub

Step-by-step guide

Create GitHub repository

• Use the template: https://github.com/NFDI4Culture/cps-demo-2
  • Select: Use this template > Create new repository
  • Choose: Where to store (Owner), set repository name, and add description.
    • Set as public.

Turn on website (GitHub Pages)

• Navigate to your repository. In the top menu select: Settings.
  • Then in settings in the left menu select: Pages.
    • In the main page under ‘Build and deployment’ change the following settings 1. Source: Set to ‘Deploy from a branch’, and; 2. Under ‘branch’ set to ‘main’ ‘/docs’ > and save.
• Turn on the new repository web address in the repos About info. Return to the repository main page by clicking ‘Code’ in top menu.
  • To the right of the page click the ‘cog wheel’ symbol. Check the box ‘Use your GitHub Pages website’ and your website address will appear.

Setup cloud development environment ‘GitHub Codespace’

GitHub Codespace provides you with an online vritual machine (VM) and integrated development environment (IDE). Once a codespace has been setup you can return to it at a later time to continue your work. Codespaces automatically save your work.

• In your repo click on the ‘Open in GitHub Codespace’ button on the README.md file.

  • This will take you to https://github.com/codespaces/
  • Click New Codespace button > Select your respository > Click ‘Create codespace’ - your codespace is now created and will launch. You can now move to the next step.

• Note:

  • View your codespaces here. This is where you can restart or manage codespaces: https://github.com/codespaces | The button on your README.md will take you here.
  • When you come to use your Codespace again you need to resume the existing Codespace.
  • Closing a Codespace: Codespaces close on their own after a default period of inactivity or select bottom left: Codespace > in Command Window - top middle > Stop Current Codespace. The Codespace will close down. Then back navigate to your repo.

Edit make a Github commit

Here there are three steps: Edit, render multi-format, and GitHub commit.

Working in your Codespace.

• Edit repo address
  • Got to and edit: _quarto.yml
  • Add your repo URL on the line repo-url: https://github.com/
    • Note: Codespace autosaves, so you don’t need to save like on your local machine.
• Quarto render: Quarto is the multi-format render engine software iused in the project.
  • Use three Quarto commands, run in this order in the Terminal and follow the prompts.
    • quarto check
    • quarto render
    • quarto preview
  • In the Terminal window at the bottom of your IDE type quarto render this will create the following outputs: Web, PDF, and DOCX. To preview your project type quarto preview, this will prompt you to open a browser window.
• GitHub commit
  • Push back to the repo
  • Go to the Source Control menu - left
  • Add a message and select: Commit and Push > you will be prompted to Stage - say yes to all.
  • Say no to the periodic Git fetch
  • Preview your outputs > open a new tab with your repo in it and navigate to the Pages link.
  • When finished you can close Codespace: as noted above or let it auto-close.

You’re all setup - congrats!