diff --git a/.devcontainer/CODESPACE_WELCOME.md b/.devcontainer/CODESPACE_WELCOME.md new file mode 100644 index 0000000..0c0c0a6 --- /dev/null +++ b/.devcontainer/CODESPACE_WELCOME.md @@ -0,0 +1,36 @@ +# Welcome to the HPC2 Codespace + +This codespace contains everything you need to build the HPC2 website. + +Hit `Ctrl + Shift + V` to view this as nicely rendered Markdown. + +Please read our [contributing guidelines](../CONTRIBUTING.md) and [readme file](../README.md) to ensure you follow good practice (e.g. no edits to the main branch). + +You can use `git` as you would locally, including pushing to the remote. You won't have to authenticate, as you're already logged in to GitHub. + +## Quick Start + +You should automatically have an open terminal with the prompt `(hpc2-jb) root@codespaces-e8c8b0:/workspace#`. +If not, open a new terminal with `Ctrl + Shift + '`; this terminal should already have the [`hpc2-jb` conda environment](../environment.yml) activated. + +### 1. Build the documentation + +```bash +jupyter-book build book/ +``` + +### 2. Serve locally + +```bash +python -m http.server -d book/_build/html +``` + +Then visit the forwarded port 8000 in your browser. VSCode should prompt you to do this with a popup, providing a URL for you to visit (the rmeote-machine equivalent of [localhost:8000](http://localhost:8000/welcome.html)): + +![alt text](open_in_browser.png) + +## Useful Commands + +- **Build book**: `jupyter-book build book/` +- **Clean build**: `jupyter-book clean book/` +- **Check links**: `jupyter-book build book/ --warningiserror --keep-going` diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000..6cba73d --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,20 @@ +# Use the official miniforge image as base +FROM condaforge/miniforge3:latest + +# Set working directory +WORKDIR /workspace + +# Copy environment file +COPY environment.yml . + +# Create conda environment from environment.yml +RUN mamba env create -f environment.yml + +# Make RUN commands use the new environment +SHELL ["conda", "run", "-n", "hpc2-jb", "/bin/bash", "-c"] + +# Activate environment in bashrc for interactive sessions +RUN echo "conda activate hpc2-jb" >> ~/.bashrc + +# Set default command to bash +CMD ["/bin/bash"] diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..b7734d6 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,36 @@ +{ + "name": "HPC2 Environment", + "dockerFile": "Dockerfile", + "context": "..", + + // Configure container + "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind", + "workspaceFolder": "/workspace", + + // Forward ports for Jupyter Book development + "forwardPorts": [8000, 8080], + + // Install VS Code extensions + "customizations": { + "vscode": { + "extensions": [ + "ms-python.python", + "ms-toolsai.jupyter", + "yzhang.markdown-all-in-one", + "davidanson.vscode-markdownlint" + ], + "settings": { + "files.defaultLanguage": "markdown" + } + }, + // this won't work locally - see https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/configuring-dev-containers/automatically-opening-files-in-the-codespaces-for-a-repository + "codespaces": { + "openFiles": [ + ".devcontainer/CODESPACE_WELCOME.md" + ] + } + }, + + // Keep container running + "shutdownAction": "stopContainer" +} diff --git a/.devcontainer/open_in_browser.png b/.devcontainer/open_in_browser.png new file mode 100644 index 0000000..cdf0407 Binary files /dev/null and b/.devcontainer/open_in_browser.png differ diff --git a/.gitignore b/.gitignore index 64a663a..49f44b5 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,3 @@ # built book **/_build/* - -# vagrant stuff -**/.vagrant/* diff --git a/README.md b/README.md index c3f41fc..e58194c 100644 --- a/README.md +++ b/README.md @@ -18,44 +18,49 @@ The current lesson format to follow as a guide: * Exercises * Key points -## Contributing to this project +## Contributing to the documentation +We welcome all contributions to this project via GitHub issues and pull requests. Please follow the guidelines on the [`CONTRIBUTING.md` file](CONTRIBUTING.md) to make sure your contributions can be easily integrated in the project. Edits must be approved by at least one user from the arcdocs group (generally RSEs & RIEs at Leeds). For larger issues that can't be solved quickly, or require greater input, please raise an Issue in the "Issues" tab. -### Working with this project locally +There are two main ways to update the documentation; via GitHub codespaces (recommended) or locally on your own machine. -You will need to install the [conda package management tool](https://docs.conda.io/en/latest/) before you can get this project working locally. -You can use the `environment.yml` file included to create a conda environment that contains all the dependencies required to get started. +### Option 1: Working with this project via GitHub Codespaces + +GitHub's codespace feature provides a cloud-based development environment that you can run from the repository's main page. To get started, switch to a new branch, then under the "Code" dropdown menu, select "Codespaces", then "Create codespace on \". The codespace will then launch in a new window, and will be ready to use after a few minutes of setup. + +Instructions for using the codespace are in the [codespace readme file](.devcontainer/CODESPACE_WELCOME.md); this will open automatically when you build the codespace. + +### Option 2: Working with this project locally + +> **_NOTE:_** This documentation is based on jupyter-book, which does not support Windows. If you are working on a Windows machine, you are recommended to use Windows Subsystem for Linux 2 (WSL2). + +In a shell with git and conda available (we recommend Miniforge): ```{bash} -$ git clone https://github.com/ARCTraining/template-jb-docs.git +# clone repository and navigate to root +$ git clone https://github.com/ARCTraining/hpc2-software.git +$ cd hpc2-software + +# create environment $ conda env create -f environment.yml ``` To build the html content locally you can use the `jupyter-book` command line tool: ```{bash} -# navigate to the repository root -$ cd template-jb-docs -# sometimes worth running jupyter-book clean book/ to remove old files -$ jupyter-book build book/ -``` -### Windows +# activate the conda environment +$ conda activate hpc2-jb -Jupyterbook now supports [Windows](https://jupyterbook.org/en/stable/advanced/windows.html) so the above steps can also be used on a Windows terminal. +# build book +$ jupyter-book build book/ -#### Set up a development environment using Vagrant -To aid with this we have created a `Vagrantfile` that can allow Windows users who have a virtualisation provider installed (such as [VirtualBox](https://www.virtualbox.org/)) and [Vagrant](https://www.vagrantup.com/) installed to create a headless virtual Linux machine that will build the jupyter book. You can do this with the following steps once you've installed a virtualisation provider and vagrant: +# if necessary, old files can be removed by running: +$ jupyter-book clean book/ ``` -# within git-bash or powershell -$ cd template-jb-docs -$ vagrant up -# to rebuild the site after changes with the vagrant box running -$ vagrant reload --provision +To preview the built html locally, you can open up a basic Python server: -# don't forget to destroy the box when you're done -$ vagrant destroy +```bash +python -m http.server -d book/_build/html ``` - -This will build the jupyter-book html files on your Windows file system (by navigating via /vagrant) so your local build will still persist after you've destroyed your vagrant box. diff --git a/Vagrantfile b/Vagrantfile deleted file mode 100644 index 039f741..0000000 --- a/Vagrantfile +++ /dev/null @@ -1,10 +0,0 @@ -# -*- mode: ruby -*- -# vi: set ft=ruby : - -Vagrant.configure("2") do |config| - config.vm.box = "hashicorp/bionic64" - - config.vm.hostname = "arcdocsSite" - - config.vm.provision :shell, path: "vagrant/bootstrap.sh" -end diff --git a/vagrant/bootstrap.sh b/vagrant/bootstrap.sh deleted file mode 100755 index ff593cb..0000000 --- a/vagrant/bootstrap.sh +++ /dev/null @@ -1,18 +0,0 @@ -#!/bin/bash - -apt-get update -apt-get install git -wget -q https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh -chmod +x miniconda.sh -./miniconda.sh -b -p /home/vagrant/miniconda -# ensures conda loaded in shell -echo "source /home/vagrant/miniconda/etc/profile.d/conda.sh" >> /home/vagrant/.bashrc -source /home/vagrant/miniconda/etc/profile.d/conda.sh -chown -R vagrant:vagrant /home/vagrant/miniconda - -# create environment and build book -cd /vagrant -conda env create -f environment.yml -conda activate arcdocs-jb -jb clean book/ -jb build book/