Skip to content

Latest commit

 

History

History
100 lines (73 loc) · 5.38 KB

README.md

File metadata and controls

100 lines (73 loc) · 5.38 KB
Raw

Introduction to Ancient Metagenomics Book

DOI

This is the source material for the Introduction to Ancient Metagenomics text book developed for the SPAAM Summer School: Introduction to Ancient Metagenomics.

Development notes

This text book has been developed as a Quarto Book, allowing for both website and PDF formats.

It is highly recommend to use the Gitpod environment to develop new material for the textbook, as it provides a fully set up writing environment.

If running locally, I highly recommend installing VS Code (or your preferred text editor/IDE) and the corresponding Quarto extension for development. This allows rendering prior to pushing to GitHub, and debugging of any issues of the website view. Make sure you also install all the dependincy requirements as described in the .gitpod.Dockerfile

GitPod

  1. Fork this repository
  2. Open on https://gitpod.io 1
    • This may take a little bit of time to pull the docker container
    • Once loaded, wait a minute or so until the preview of the textbook is loaded (you will see lots of text being printed in the console)
    • To load the preview, press the 'open preview' button in the bottom right image
    • If you miss the message above, press 'Ports' in the bottom right toolbar, and click the running URL to open in a new tab
  3. Make a new branch e.g. git switch -c new-chapter
  4. If adding a new chapter, make a new .qmd file in the root directory, else edit the existing .qmd file of your choice
  5. Images for the chapter should go into assets/images/chapters/
    • Do not place in docs/assets/images/chapters/!
  6. References in BibTex for the chapter should go a references.bib file into assets/references/<chapter_name>.bib
  7. Conda environment files go in docs/assets/envs/<chapter_name>.bib
  8. If adding a new chapter, add the .qmd file to the _quarto.yml config file in the chapters: scope
  9. Refresh the preview tab to check your chapter renders correctly
  10. Commit, push to GitHub, and open a PR against the main branch 2

![WARNING] Only push .qmd, images, .bib files etc! Do not push html json files etc., from the rendering!

General tips:

  • Use the native markdown syntax for images (![](assets/images/chapters/<your_image>.png))
  • For note blocks see the Quarto docs

Locally

If adding a new section chapter:

  1. Clone this repository

  2. Make a new branch e.g. git switch -c new-chapter

  3. Make a new .qmd file in the root directory

  4. Images for the chapter should go into assets/images/chapters/

    • Do not place in docs/assets/images/chapters/!

  5. References in BibTex for the chapter should go a references.bib file into assets/references/chapters/<chapter>

  6. Add the .qmd file to the _quarto.yml config file in the chapters: scope

  7. Render the book the extensions' Quarto: Render Book command, or run the following

    quarto preview intro-to-ancient-metagenomics-book/ --render all --no-browser --no-watch-inputs

  8. Commit, push to GitHub, and open a PR against the main branch 2

Warning

Only push .qmd, images, .bib files etc! Do not push html json files etc., from the rendering!

General tips:

  • Use the native markdown syntax for images (![](assets/images/chapters/<your_image>.png))
  • For note blocks see the Quarto docs

Release procedure

Before

  • Check for any major TODOs in the book
  • Make sure authors updated
    • On authors.qmd
    • In citations.gff
    • In citing-this-book.qmd (set DOI to root DOI)
  • Make sure cover images updated
    • Stating (Edition 202X)
    • Update contributors on jacket back
  • Make sure all software installation instructions/conda yaml files are up to date
  • Make sure all data files uploaded, and if necessary Zenodo DOI updated
    • Update from previous upload
    • Make sure to bump year to title
    • Version system: YYYY.point release (2024.0, 2024.1)
    • Make sure to update authors if required
  • Update Zenodo DOI for each chapter
  • Make sure footnotes year fixed everywhere (_quarto.yml)
  • Update release date in citations.cff

After

  • In citing-this-book.qmd set DOI to release DOI

Notes

Footnotes

  1. I recommend installing the gitpod chrome extension which adds a nice shortcut button to the github repository next to the green 'code' button. ↩

  2. If you're using gitpod and have a 'don't have permissions' error when pushing you may need to do the following: (1) Go to: https://gitpod.io/user/integrations (2) Press triple dots next to the GitHub Git Provider (3) Edit permissions so all permissions are ticked except for read:user ↩ ↩2