Rendeiro group

Lab manual

Welcome to the Rendeiro Lab Manual.

This manual provides comprehensive information about the lab's culture, procedures, and workflows to ensure a collaborative and efficient research environment.

The manual is hosted in the lab-manual repository on GitHub. It is written in Markdown and can be converted to HTML and PDF using Pandoc.

This manual is open source and maintained collaboratively. Anyone on GitHub can propose changes.

Editing the manual

To contribute an adition or change to the manual:

  1. Edit or create files directly on GitHub, or locally on your computer.
  2. Submit a pull request with a clear, one-line description of the changes made.
  3. Follow best practices by adding reviewers and referencing related issues, if applicable.

Tip: to add a table of contents to a new file document, use mdformat-toc. Insert <!-- mdformat-toc start --> where the table of contents should appear, and run mdformat <file.md> on the edited file, or make format to format all.

Building the manual locally

To preview changes locally before committing to Github and deploying on the lab website, you can build the manual locally using the provided tools. Ensure you have the necessary dependencies installed: - Pandoc - wkhtmltopdf

To streamline the development process the project includes a Makefile. Key targets include:

  • format: Formats Markdown files consistently using mdformat.
  • build: Converts the manual into a single HTML file using pandoc and generates a PDF file using wkhtmltopdf.
  • clean: Removes generated files to ensure a fresh build.

Styling for the manual is controlled by a custom CSS file, which ensures a nice appearance in both HTML and PDF formats.

Future improvements

Some outstanding tasks to improve the manual's content, style and accessibility:

  • Improve and include public data page
  • Add additional resources on project planning
  • Add section on 'Developing a project'
  • Add section on 'Publications'
  • Add section on 'Authorship'
  • Add section on 'Engaging in new projects'
  • Remove hackaton ideas section from 'Communication'
  • Add proper href for all links
  • Align all file names with h1 heading (for easy linking and easier website deploy)
  • Update build and dependencies docs
  • Website deployment
    • Set up
    • Fix ul, ol and table styling
    • Fix intra-manual links (ending .md)
    • Fix Python code blocks highlighting
    • Build only on tagged versions, not on main

Acknowledgements

We thank the following labs for sharing their open-source lab manuals, which inspired this project:

Edit this page on GitHub