From 76b11a31d7a640bd59932593e3404d2f1ce9c96d Mon Sep 17 00:00:00 2001 From: Neil Shephard Date: Fri, 19 Jan 2024 12:22:47 +0000 Subject: [PATCH] Setup instructions; Customise README.md Initial customisation of generic materials pointing people to instructions for installing Conda on their operating system. Rewrites the `README.md` for the particular lesson. --- README.md | 91 ++++++++++---------------------- index.md | 4 +- instructors/instructor-notes.md | 3 +- learners/data/topostats-data.zip | 0 learners/setup.md | 42 +++++++++++---- 5 files changed, 64 insertions(+), 76 deletions(-) create mode 100644 learners/data/topostats-data.zip diff --git a/README.md b/README.md index 57064af..68a5b81 100644 --- a/README.md +++ b/README.md @@ -1,72 +1,39 @@ -# The Carpentries Workbench Template Markdown Lesson +# TopoStats AFM Image Processing Tutorial -This lesson is a template lesson that uses [The Carpentries Workbench][workbench]. +This lesson uses [The Carpentries Workbench][workbench] to develop training material for the [TopoStats][topostats] +Atomic Force Microscopy batch image processing software. -## Note about lesson life cycle stage -Although the `config.yaml` states the life cycle stage as pre-alpha, **the template is stable and ready to use**. The life cycle stage is preset to `"pre-alpha"` as this setting is appropriate for new lessons initialised using the template. +The course material is rendered and available [online][topostats-training]. -## Create a new repository from this template +## Code of Conduct -To use this template to start a new lesson repository, -make sure you're logged into Github. -Visit https://github.com/carpentries/workbench-template-md/generate -and follow the instructions. -Checking the 'Include all branches' option will save some time waiting for the first website build -when your new repository is initialised. +Please refer to the `CODE_OF_CONDUCT.md` at the top level of this repository. -If you have any questions, contact [@tobyhodges](https://github.com/tobyhodges) +## Contributing -## Configure a new lesson +Contributions are welcome, please see the `CONTRIBUTING.md` file at the top level of this repository. -Follow the steps below to -complete the initial configuration of a new lesson repository built from this template: +### Building Locally -1. **Make sure GitHub Pages is activated:** - navigate to _Settings_, - select _Pages_ from the left sidebar, - and make sure that `gh-pages` is selected as the branch to build from. - If no `gh-pages` branch is available, check _Actions_ to see if the first - website build workflows are still running. - The branch should become available when those have completed. -1. **Adjust the `config.yaml` file:** - this file contains global parameters for your lesson site. - Individual fields within the file are documented with comments (beginning with `#`) - At minimum, you should adjust all the fields marked 'FIXME': - - `title` - - `created` - - `keywords` - - `life_cycle` (the default, _pre-alpha_, is the appropriate for brand new lessons) - - `contact` -1. **Annotate the repository** with site URL and topic tags: - navigate back to the repository landing page and - click on the gear wheel/cog icon (similar to ⚙️) - at the top-right of the _About_ box. - Check the "Use your GitHub Pages website" option, - and [add some keywords and other annotations to describe your lesson](https://cdh.carpentries.org/the-carpentries-incubator.html#topic-tags) - in the _Topics_ field. - At minimum, these should include: - - `lesson` - - the life cycle of the lesson (e.g. `pre-alpha`) - - the human language the lesson is written in (e.g. `deutsch`) -1. **Adjust the - `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and `LICENSE.md` files** - as appropriate for your project. - - `CODE_OF_CONDUCT.md`: - if you are using this template for a project outside The Carpentries, - you should adjust this file to describe - who should be contacted with Code of Conduct reports, - and how those reports will be handled. - - `CONTRIBUTING.md`: - depending on the current state and maturity of your project, - the contents of the template Contributing Guide may not be appropriate. - You should adjust the file to help guide contributors on how best - to get involved and make an impact on your lesson. - - `LICENSE.md`: - in line with the terms of the CC-BY license, - you should ensure that the copyright information - provided in the license file is accurate for your project. -1. **Update this README with - [relevant information about your lesson](https://carpentries.github.io/lesson-development-training/collaborating-newcomers.html#readme)** - and delete this section. +To render these pages locally you need to have [R][r] installed. Instructions are +[available](https://carpentries.github.io/workbench/#installation) but some additional steps have been taken to make +sure the environment is reproducible. +Once you have installed the dependencies you can render the pages locally by starting R in the project root and +running... + +``` r +sandpaper::serve() +``` + +This will build the pages and start a local web-server in R and open it in your default browser. These pages are "live" +and as you edit and save them the web-site will be rebuilt and the pages updated. + +## Licensing + +Please refer to the `LICENSING.md` at the top level of this repository. + +[r]: https://www.r-project.org/ +[topostats]: https://afm-spm.github.io/topostats +[topostats-training]: https://afm-spm.github.io/topostats-training [workbench]: https://carpentries.github.io/sandpaper-docs/ diff --git a/index.md b/index.md index af66276..676a771 100644 --- a/index.md +++ b/index.md @@ -2,8 +2,8 @@ site: sandpaper::sandpaper_site --- -This is a new lesson built with [The Carpentries Workbench][workbench]. +Welcome to the training material for the [TopoStats][topostats] Atomic Force Microscopy image processing software. +[topostats]: https://afm-spm.github.io/TopoStats [workbench]: https://carpentries.github.io/sandpaper-docs - diff --git a/instructors/instructor-notes.md b/instructors/instructor-notes.md index d9a67aa..09d26aa 100644 --- a/instructors/instructor-notes.md +++ b/instructors/instructor-notes.md @@ -2,4 +2,5 @@ title: 'Instructor Notes' --- -This is a placeholder file. Please add content here. +Instructors should be familiar with the material contained in this course prior to delivery. It might be useful to run +through the exercises yourself at least once. diff --git a/learners/data/topostats-data.zip b/learners/data/topostats-data.zip new file mode 100644 index 0000000..e69de29 diff --git a/learners/setup.md b/learners/setup.md index 46eddd1..6f33ef8 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -2,8 +2,15 @@ title: Setup --- -FIXME: Setup instructions live in this document. Please specify the tools and -the data sets the Learner needs to have installed. +This course teaches you the basics of using [TopoStats][topostats] to process Atomic Force Microscopy images. TopoStats +is software written in the [Python][python] programming language so you will need this installed on your system. Most +GNU/Linux and OSX operating systems already have Python installed however in order to make a reproducible environment +available we will guide you through how to use [Conda][conda] environments to setup and install an isolated environment +for installing TopoStats and its dependencies. + +Because of the vast heterogeneity in AFM images we have created a sample data set for you to work through this tutorial +with. If time permits at the end of the class you can try processing your own images and instructors may be able to help +with any problems that you encounter. ## Data Sets @@ -12,18 +19,27 @@ FIXME: place any data you want learners to use in `episodes/data` and then use a relative link ( [data zip file](data/lesson-data.zip) ) to provide a link to it, replacing the example.com link. --> -Download the [data zip file](https://example.com/FIXME) and unzip it to your Desktop +Download the [data zip file](data/topostats-data.zip) and unzip it to your Desktop ## Software Setup ::::::::::::::::::::::::::::::::::::::: discussion -### Details +### Conda + +[Conda][conda] is an open-source, cross-platform, language-agnostic package manager and environment +management system for the popular programming and data science languages [Python][python] and [R][r]. For the purposes +of this class we will only be using the support for Python. + +We ask that you install Conda on your laptops prior to the class so we can maximise the time available for covering the +course material. You do _not_ need to worry about creating any Conda environments before the class starts, we cover that +as part of the material. + +The official [installation instructions](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html) +are comprehensive and detailed and should get you setup. -Setup for different systems can be presented in dropdown menus via a `solution` -tag. They will join to this discussion block, so you can give a general overview -of the software used in this lesson here and fill out the individual operating -systems (and potentially add more, e.g. online setup) in the solutions blocks. +If you find you are having problems installing the software please contact [the +instructors](mailto:topostats@sheffield.ac.uk) for assistance. ::::::::::::::::::::::::::::::::::::::::::::::::::: @@ -31,7 +47,7 @@ systems (and potentially add more, e.g. online setup) in the solutions blocks. ### Windows -Use PuTTY +[Installing Conda on Windows](https://docs.conda.io/projects/conda/en/stable/user-guide/install/windows.html) ::::::::::::::::::::::::: @@ -39,7 +55,7 @@ Use PuTTY ### MacOS -Use Terminal.app +[Installing Conda on macOS](https://docs.conda.io/projects/conda/en/stable/user-guide/install/macos.html) ::::::::::::::::::::::::: @@ -48,7 +64,11 @@ Use Terminal.app ### Linux -Use Terminal +[Installing Conda on Linux](https://docs.conda.io/projects/conda/en/stable/user-guide/install/linux.html) ::::::::::::::::::::::::: +[conda]: https://docs.conda.io/en/latest/ +[python]: https://www.python.org +[r]: https://www.r-project.org/ +[topostats]: https://afm-spm.github.io/TopoStats