From 7cbf4da916e950f1e5d62b5eb56a230620e47989 Mon Sep 17 00:00:00 2001 From: Henry Webel Date: Wed, 2 Oct 2024 18:53:43 +0200 Subject: [PATCH] :memo: add some hints for the workshop - tested on codespaces using 'open in a codespace' from template. --- README.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0f51197..32da005 100644 --- a/README.md +++ b/README.md @@ -2,20 +2,34 @@ ## Instructions -### 1. Fork repository +### 1. Create new repository based on this template + +Create a template based on +[this repository](https://github.com/enryH/notes_template) +by clicking on the "Use this template" button, +see instructions +[here](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template) - now you are already publish the site which looks identical to the template site (see it here) - jump to step 5 to do that directly. -### 2. Open in GitHub Codespaces +### 2. Open in GitHub Codespaces (or locally) - go to [github.com/codespaces](https://github.com/codespaces) - create a new codespace using the forked repository +> If you are done, remember to delete the codespace to not see your free credit or money +> wasted. Also inactive (stopped) codespaces use storage for the last 30 days. + ### 3. Edit files - update in `conf.py` at least the author, project and copyright information at the top + - also update two urls to your repository: + ```json + "github_url": "https://github.com/enryh/", + "repository_url": "https://github.com/enryh/notes_template", + ``` - write something about you in `about.md` - write articles in `folder_topic/article_topic.md` - update the `index.md` file to include new files @@ -24,7 +38,8 @@ ### 4. Build the site locally -> Have look at `.github/workflows/build-website.yaml` to see how the site is built. +> Have look at `.github/workflows/build_website.yaml` to see how the site is built +> if you are interested. - Open a terminal (GitHub Codespaces) - install required packages from [`requirements.txt`](requirements.txt): @@ -35,9 +50,13 @@ ```bash sphinx-build -n -W --keep-going -b html ./ ./_build/ ``` + in case the command is not found, try: + ```bash + python -m sphinx -n -W --keep-going -b html ./ ./_build/ + ``` - open the site in a browser: - - install "Live Preview" extension in Visual Studio Code - - open the `_build/index.html` file in the browser + - install ["Live Preview" extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) in Visual Studio Code + - open the `_build/index.html` file in the browser (right-click, "Show Preview") ### 5. Publish the site