Name: MelBioInf_docs
Owner: Melbourne Bioinformatics
Description: LSCC documentation in markdown format
Created: 2015-05-06 07:30:07.0
Updated: 2017-10-05 13:27:25.0
Pushed: 2017-11-28 06:42:10.0
Homepage: null
Size: 23812
Language: HTML
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|---|---|
| Bernie Pope | 2017-02-17 06:28:53.0 | 21 |
| Ira Cooke | 2015-10-28 05:20:11.0 | 2 |
| Slugger70 | 2018-03-06 21:41:58.0 | 71 |
| claresloggett | 2018-03-21 01:56:58.0 | 45 |
| Andrew Robinson | 2015-09-20 23:11:20.0 | 23 |
| Madison Flannery | 2016-06-08 02:11:58.0 | 2 |
| Nuwan Goonasekera | 2018-03-06 09:27:53.0 | 1 |
| Matthew Wakefield | 2015-08-26 02:32:51.0 | 6 |
| Jessica Chung | 2017-11-14 07:17:26.0 | 29 |
| Michael Milton | 2018-03-21 01:25:10.0 | 17 |
| Anna Syme | 2018-03-16 00:43:22.0 | 22 |
| bjmoran | 2017-02-17 06:27:11.0 | 4 |
Other Committers
| User | Most Recent Commit | # Commits |
|---|
These tutorials have been developed by Melbourne Bioinformatics (formerly VLSCI) and are used in Melbourne Bioinformatics hands-on workshops.
The tutorials have been deployed here: http://melbournebioinformatics.github.io/MelBioInf_docs/
Tutorials are written in Markdown and built with MkDocs.
All documentation source files are under docs/. Tutorials are stored under docs/tutorials/.
Slides for workshops are currently stored in Google Drive as Google Slides. Slides may optionally be added to this repository as e.g. Markdown or PDF.
Each tutorial subdirectory under docs/tutorials/ should contain:
.md) document with tutorial instructions. One of these should be the main tutorial document and be listed in mkdocs.yml in the top directory of this repository.README.md Markdown document containing suggested PR reviewers and the location of any relevant Google Slides (or any other slides that cannot be stored in the repository directly).media subdirectory with images that will be used by MkDocs.Tutorials are built and deployed to the gh-pages branch using MkDocs, and then appear at http://melbournebioinformatics.github.io/MelBioInf_docs/.
This section is a guide to contributing edits to the repository. For a guide to which files to edit, see Making changes to tutorial instructions, Making changes to slides, and Adding a new tutorial.
You should do your work in a fork under your own github account:
git clone https://github.com/<your_account>/MelBioInf_docsIt is often a good idea to make a separate branch in your fork to work on your changes.
If the repository has been edited since you forked it, you will need to bring your fork up to date before you can contribute changes:
remote add upstream https://github.com/melbournebioinformatics/MelBioInf_docs
fetch upstream
merge upstream/master
We are using the Python package MkDocs.
I recommend installing MkDocs into a virtualenv:
on3 -m venv mkdocs_dev # or python2 -m virtualenv mkdocs_dev
ce mkdocs_dev/bin/activate
install -r requirements.txt
Once you have mkdocs installed (and in your PATH) then you can preview the website by running the following command in the top directory of this repository:
cs serve
This will start up a web server hosting on a local URL, like so:
ing at: http://127.0.0.1:8000/
reload enabled.
ctrl+c to quit.
You can view the site if you point your browser at the specified URL.
MkDocs will automatically try to update the local site preview if you edit the documentation pages.
Alternatively, you can build the site locally using mkdocs build. This will put all the HTML, CSS, Javascript etcetera for the site in the directory called site, but unlike mkdocs serve, will not run a local webserver or update the build when you make changes.
It is a good idea to preview your changes locally before pushing them.
You can deploy changes to your fork. This will allow you (and PR reviewers) to view your changes online prior to merging your pull request.
Run:
cs gh-deploy
This will build the Markdown into HTML in your fork's gh-pages branch, AND immediately push the result without any further chance to review it. Your build should be
visible at http://<your_account>.github.io/lscc_docs/tutorials.
Commit your changes. Then push them to your fork with git push origin master.
Open your fork in github at https://github.com/<your_account>/MelBioInf_docs and create a pull request.
If your fork is up to date, you should see “These branches can be automatically merged” while you are creating the pull request. If your fork is not up to date you should bring it up to date (see Sync with upstream)) and resolve any merge conflicts before creating the pull request.
Ideally you should have someone else check and merge your pull request rather than do it yourself. Suggested reviewers for each tutorial are in that tutorial's README.md.
Preferably, change one major thing per pull request - e.g. edit one tutorial in one pull request, and make a separate pull request if you want to edit another tutorial.
If someone has asked you to merge their PR, or if you are merging in your own:
http://<requesters_account>.github.io/MelBioInf_docs/ if the author has run mkdocs gh-deploy on their fork. Or,clone https://github.com/melbournebioinformatics/MelBioInf_docs
elBioInf_docs
cs gh-deploy
Check that the updated tutorial appears under http://melbournebioinformatics.github.io/MelBioInf_docs/
Tutorial instructions are stored as Markdown and fully versioned, so you can just edit the .md files containing those instructions and commit your changes. Follow the instructions above to contribute changes.
New media can be added to the tutorial's media subdirectory and linked in to the Markdown document.
For slides stored in Google Drive, a link should be recorded in docs/tutorials/<tutorialname>/README.md. This link should point to the Google slides source (not PDF) where possible.
If you have made an alternate version of the slides for a workshop, you can list the link for it under “Other slides” in the README.md. Give some kind of description for this alternate version, e.g. “slides for a clinical audience”, “slides for bioinformaticians at GCC”, or “Clare's abbreviated 5-minute slides”.
If you want to update the latest set of slides for a workshop:
README.md to a bullet point under “Other slides”. Give some kind of description for this old version, even if it is just something like “Slides prior to June 2017 edits”.LSCC_shared/capacity_building/tutorials_workshops/ or LSCC_shared/capacity_building/LSCC_NGSschool/.LSCC_shared folder, they will still be accessible to anyone with access permissions for that folder.README.md.Don't be afraid to replace the current slides with your version if you think it is more up to date. The old slides are still accessible.
To create your new tutorial:
docs/tutorials with a meaningful name, e.g. docs/tutorials/molecular_modellingdocs/tutorials/molecular_modelling/molecular_modelling.md. You can use other tutorials as a template for the layout.mkdocs.yml in the correct section. This will cause a link to it to appear in the menu of tutorials.media subdirectory, e.g. docs/tutorials/molecular_modelling/media. Copy in any images you need from other tutorials (e.g. logos). You can add any images here that you want to link into your Markdown documents.README.md file in your tutorial subdirectory, e.g. docs/tutorials/molecular_modelling/README.md. You can copy the format of this file from another tutorial. Add your own name as a PR reviewer for future changes.Add slides:
LSCC_shared/capacity_building/LSCC_NGSschool.README.md and label them “Current slides”.Once you've created your content:
git add.