Florida International University, Biscayne Bay Campus, Marine Science Building, labs manual
For incoming, current, and outgoing members of the MSB, to be collaboratively edited by its users, rather than the work of one individual. To make changes, do a pull request and your changes will be reviewed then pulled into the manual for everyone to see & benefit from.
This file/page is edited in README.md and rendered/published to https://github.com/SimonDedman/msb-lab-manual i.e. the GitHub code project page. Quarto (qmd) files within the project directory are rendered/published to the actual online manual, https://simondedman.github.io/msb-lab-manual
- Have a Github account.
- Setup Git on RStudio and Associate with GitHub.
- Fork the project (e.g. this one) on the project's Github webpage (top right). This copies the external project to your own Github account.
- In your GitHub forked project webpage, click the green
codebutton, copy git address. - In your filesystem (/home, My Computer, etc., i.e. not online, look away from your browser), choose a parent folder to host the project folder and its files and folders. The result will be a folder called "msb-lab-manual" WITHIN the folder you choose, so I suggest either something FIU-specific (e.g. /FIU/Code) or somewhere which will host multiple of your own projects and forked projects in the future (e.g. /R). In that folder open a terminal AKA command prompt, and type
git clone [gitaddress]. You will need to have git installed (if you use linux it's already installed, well done you). - Go to the new subfolder and open the .Rproj file in RStudio (hopefully you can just doubleclick it).
Go to the QMD file for a page you want to edit and make changes using RMarkdown or Quarto formatting, depending on the file. Quarto text formatting conventions seem to be the same as markdown, but it includes more features in the YAML headers and code chunks.
- Make changes in your local files in RStudio, e.g. open the relevant qmd file for a page you want to change, test your edits bywith the Render button, then type
devtools::document()in the console to synchronise any documentation changes resulting from your edits (unlikely for qmd files but good practice generally), then click the "GIT" icon in the top bar of RStudio, "Commit...", select all the files on the left hand side so they're all ticked (staged to be committed; I ctrl+shift+click the bottom one while the top one's selected, then hit the space bar), type a commit message briefly explaining what these changes are, then Commit, close, then the Push button in the top right. The edits are now pushed from your local machine to your OWN Github forked project. And NOT to the remote/main/original project you forked from. - Go to original (other person's) package, pull requests, create, "compare across forks", select your fork as the right hand side. "Create pull request" button.
- If it's not automatically named correctly, name it well. See this.
- Pull request example.
The Github R project file pertaining to the central frame on the first page (from "Welcome" to the bottom, not including the top and side panes) is index.qmd. The top and side bits are edited in _quarto.yml (chapters are autopopulated: 1 = index.qmd (this file), then alphabetically by qmd filenames in the root folder, pulling the name from the name of the header in each file). References are tagged thus: [@wilson2017], corresponding to a bibtext entry added to references.bib. If creating a new site like this one, also edit sitemap.xml and possibly also robots.txt.
Adding more complex stuff than just text is possible and very much encouraged, e.g. the table on the lab members page. Look around for existing examples on this site and elsewhere you can copy from rather than trying to bash your head against the wall. Also check the Github actions page, though this might only be useful for the package owner...
The structure for this manual was forked from Gavin Fay's FayLab manual following these steps (plus some wrangling to get it to work), which was itself developed as part of the Openscapes Champions program.
