diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8c095d8..f00f2fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,23 +46,23 @@ and to meet some of our community members. ## Where to Contribute 1. If you wish to change this lesson, - please work in , - which can be viewed at . + please work in , + which can be viewed at . -2. If you wish to change the example lesson, +2. If you wish to change the Carpentries example lesson, please work in , which documents the format of our lessons and can be viewed at . -3. If you wish to change the template used for workshop websites, +3. If you wish to change the template used for Carpentries workshop websites, please work in . The home page of that repository explains how to set up workshop websites, while the extra pages in provide more background on our design choices. -4. If you wish to change CSS style files, tools, +4. If you wish to change DUNE CSS style files, tools, or HTML boilerplate for lessons or workshops stored in `_includes` or `_layouts`, - please work in . + please work in . ## What to Contribute diff --git a/_episodes/00-Local-Setup-For-Local-Build.md b/_episodes/00-Local-Setup-For-Local-Build.md new file mode 100644 index 0000000..3173dab --- /dev/null +++ b/_episodes/00-Local-Setup-For-Local-Build.md @@ -0,0 +1,30 @@ +--- +title: Local Setup Instructions +teaching: 30 +exercises: 0 +questions: +- How can I set up a local server to check my lesson +objectives: +- Learn how to set up locally +keypoints: +- This is the hard part, need to get ruby +--- + + +## Instructions for local setup to build your lessons - very useful + + +> #### Note: +> The Carpentries provide excellent instructions and examples at: [https://carpentries.github.io/lesson-example/setup.html](https://carpentries.github.io/lesson-example/setup.html). +> Carpentries has moved on to an 'R' based system which we are not using. We are still using this older format. +{: .callout} + + +## Do local setup for local rendering (optional) + +Follow the instructions [https://carpentries.github.io/lesson-example/setup.html#setup-for-local-rendering-of-the-lessons-optional](https://carpentries.github.io/lesson-example/setup.html#setup-for-local-rendering-of-the-lessons-optional) for setup on your local machine - in principle this is optional but in practice it is really helpful. You are going to need ruby and pyYAML. I used conda on a mac but they have instructions for Windows, Mac and UNIX. + +> #### Alert!!! +> At this point you should stop following their instructions and start using our github template to avoid overwriting DUNE specific items. +{: .callout} + diff --git a/_episodes/01-How-to-make-a-lesson.md b/_episodes/01-How-to-make-a-lesson.md new file mode 100644 index 0000000..66a7a33 --- /dev/null +++ b/_episodes/01-How-to-make-a-lesson.md @@ -0,0 +1,120 @@ +--- +title: How to make a Lesson for DUNE +teaching: 30 +exercises: 0 +questions: +- How can I make a lesson like this from scratch using the DUNE template +objectives: +- Learn how to set up locally to build a lesson and to deploy it. +keypoints: +- If you can do basic markdown, you can do this. +--- + + +## Here I describe how I built this lesson. You can follow along. + + + +> #### Note: +> Check out the [previous episode]({{ site.baseurl }}/00-Local-Setup-For-Local-Build.html)to set up a local server and to do local builds. +{: .callout} + +## First you need to decide on a name for your new lesson. + +> #### Note: +> Because github insists on using gh_pages for deployment, it is good to use your own github account for initial (and ongoing) development and pull over to /DUNE/ for the official version rather than using branches in the /DUNE/ github area. +{: .callout} + +## Do local setup for local rendering (optional) + +Then follow the instructions [https://carpentries.github.io/lesson-example/setup.html#setup-for-local-rendering-of-the-lessons-optional](https://carpentries.github.io/lesson-example/setup.html#setup-for-local-rendering-of-the-lessons-optional) for setup on your local machine - in principle this is optional but in practice it is really helpful. You are going to need ruby and pyYAML. I used conda on a mac but they have instructions for Windows, Mac and UNIX. + +> #### Alert!!! +> At this point you should stop following their instructions and start using our template to avoid overwriting DUNE specific items. +{: .callout} + +## Then import this template. + +- Use the [GitHub’s importer](https://github.com/new/import) to make a copy of this repo in your own GitHub account. (Note: This is like a GitHub Fork, but not connected to the upstream changes) + +- Put the URL of this repository, that is https://github.com/DUNE/lesson-template.git in the “Your old repository’s clone URL” box. + +- Select the owner for your new repository (you). + +- Set the name you chose for your lesson repository. + +- Make sure the repository is public. + +> #### Note: +> Please import to your own account and new lesson, work there and then move it over to `/DUNE/` once you have a decent draft in place. +{: .callout} + + +The difference from the carpentries is the addition of the DUNE logo and stuff specific to our lessons. + + +## now make a local copy on the gh-pages branch and edit away +~~~ +git clone -b gh-pages +~~~ +{: .language-bash} + +You need to look at the following pages. + +- `_config.yml ` to set the title and other parameters for the lesson +- `AUTHORS` to tell people who is doing this +- `CITATION` how to cite the page - often just the URL +- `LICENSE` you can keep it as is +- `LICENSE.md` +- `README.md` +- `reference.md` +- `setup.md` This is currently the full setup for new users. + +Then throw your individual modules into `_episodes` with leading numbers to set the order. The code will follow the ordering of the files in `_episodes`. + +There are very nice examples and a formatting tutorial at: [https://carpentries.github.io/lesson-example/](https://carpentries.github.io/lesson-example/) + +You can throw supplemental stuff into `_extras`. + +## You can then build your site locally either as a server or just a local site. + +### local site + +~~~ +make site +~~~ +{: .language-bash} + +This does a lot of setup - it's pulling in a lot of ruby "gem" files. + +Your local site will be in _sites/index.html + +#### Checking + +~~~ +make lesson-check +~~~ +{: .language-bash} + +will tell you about all the FIXME's you haven't fixed and missing formatting syntax. + +### local server + +~~~ +make serve +~~~ +{: .language-bash} + +will launch a web server and a site at: `http://127.0.0.1:4000` + +You need to reload the web site to see your changes. + +> ### Note: +These will hang around until you kill them so if you try to launch twice so look for processes with: +{: .callout} + + +~~~ +ps -ef | grep jekyll +~~~ +{: .language-bash} \ No newline at end of file diff --git a/_episodes/01_How_to_make_a_lesson.md b/_episodes/01_How_to_make_a_lesson.md deleted file mode 100644 index e69de29..0000000 diff --git a/_extras/TutorialsMasterList.md b/_extras/TutorialsMasterList.md deleted file mode 100644 index 6a5e196..0000000 --- a/_extras/TutorialsMasterList.md +++ /dev/null @@ -1,15 +0,0 @@ -# List of DUNE computing tutorials - - -## [Computing Basics](https://dune.github.io/computing-basics/) -A starting point for new DUNE people. How to log in, access disk and run basic jobs at FNAL and CERN. - -## [The Justin Workflow System](https://justin.dune.hep.ac.uk/docs/) -How to use the Justin Workflow system to submit jobs and access data. [Metacat/Rucio/Justin Tutorial](https://docs.dunescience.org/cgi-bin/sso/RetrieveFile?docid=30145) has step by step instructions. - -## [LArTPC Reconstruction Training](https://indico.ph.ed.ac.uk/event/268/) -Annual training on LArTPC reconstruction and simulation methods. - -## [FAQ](https://github.com/orgs/DUNE/projects/19/views/1) -Common error messages and frequently asked questions about DUNE Computing. - diff --git a/_extras/discuss.md b/_extras/discuss.md deleted file mode 100644 index e69de29..0000000