|
1 | | -# Template for a static website using Sphinx and GitHub Pages |
| 1 | +# Data visualization in Python |
2 | 2 |
|
3 | | -You can find a recording of the [instructions](#instructions) described below on youtube: |
4 | | -[](https://www.youtube.com/watch?v=XolIezJtSPI) |
| 3 | +> Workshop material for 19th November 2025 |
6 | 4 |
|
7 | | -## Instructions |
8 | | - |
9 | | -### 1. Create new repository based on this template |
10 | | - |
11 | | -Create a template based on |
12 | | -[this repository](https://github.com/enryH/notes_template) |
13 | | -by clicking on the "Use this template" button, |
14 | | -see instructions |
15 | | -[here](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template) |
16 | | - |
17 | | -- now you are already publish the site which looks identical to the template site |
18 | | - (see it here) |
19 | | -- jump to step 5 to do that directly. |
20 | | - |
21 | | -### 2. Open in GitHub Codespaces (or locally) |
22 | | - |
23 | | -- go to [github.com/codespaces](https://github.com/codespaces) or use the "Code" button |
24 | | - and select "Open with Codespaces" |
25 | | -- create a new codespace using the newly created repository |
26 | | - |
27 | | -> If you are done, remember to delete the codespace to not see your free credit or money |
28 | | -> wasted. Also inactive (stopped) codespaces use storage for the last 30 days. |
29 | | -> See [this youtube video](https://youtu.be/gY0usMl2o5I) on how to do it: |
30 | | -
|
31 | | -[](https://www.youtube.com/watch?v=gY0usMl2o5I) |
33 | | - |
34 | | -### 3. Edit files |
35 | | - |
36 | | -You will need to know the Markdown to format your text. See |
37 | | -[this overview on GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) |
38 | | -or [this cheatsheet](https://www.markdownguide.org/cheat-sheet/) to get started. |
39 | | - |
40 | | -- update in `conf.py` at least the author, project and copyright information at the top |
41 | | - - also update two urls to your repository: |
42 | | - ```json |
43 | | - "github_url": "https://github.com/enryh/", |
44 | | - "repository_url": "https://github.com/enryh/notes_template", |
45 | | - ``` |
46 | | -- write something about you in `about.md` |
47 | | -- write articles in `folder_topic/article_topic.md` |
48 | | -- update the `index.md` file to include new files |
49 | | -- use [pandoc](https://pandoc.org/try/) to convert your previous files into markdown or |
50 | | - reStructuredText |
51 | | - |
52 | | -Troubleshooting: |
53 | | - - don't forget to add new files to the `index.md` file |
54 | | - - each document should have a title (`# title`) using a main heading and otherwise |
55 | | - nested headlines (subheadings followed by sub-subheadings) |
56 | | - |
57 | | -### 4. Build the site locally |
58 | | - |
59 | | -Sphinx uses the configuration file `conf.py` to set up the site. The `requirements.txt` file |
60 | | -contain extensions and themes that are used additionally to sphinx to build the site. |
61 | | -The layout of the website is defined in the `index.md` file. |
62 | | - |
63 | | -> Have look at `.github/workflows/build_website.yaml` to see how the site is built |
64 | | -> if you are interested. |
65 | | - |
66 | | -- Open a terminal (GitHub Codespaces) |
67 | | -- install required packages from [`requirements.txt`](requirements.txt): |
68 | | - ```bash |
69 | | - pip install -r requirements.txt |
70 | | - ``` |
71 | | -- build the site (you could set an alias if you want): |
72 | | - ```bash |
73 | | - sphinx-build -n -W --keep-going -b html ./ ./_build/ |
74 | | - ``` |
75 | | - in case the command is not found, try: |
76 | | - ```bash |
77 | | - python -m sphinx -n -W --keep-going -b html ./ ./_build/ |
78 | | - ``` |
79 | | -- open the site in a browser: |
80 | | - - install ["Live Preview" extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) in Visual Studio Code |
81 | | - - open the `_build/index.html` file in the browser (right-click, "Show Preview") |
82 | | - |
83 | | -### 5. Publish the site |
84 | | - |
85 | | -Follow |
86 | | -[these instructions](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) |
87 | | -to publish the website using GitHub Pages. |
88 | | - |
89 | | -- Select the `gh-pages` branch as the source for the GitHub Pages site (currently step 7) |
90 | | -- add the deployed url to your "About" on the right sight of the repository |
91 | | - |
92 | | - |
93 | | -## Changing the topic |
94 | | - |
95 | | -If you want to change the topic you can browse templates on the follwing site: [sphinx-themes.org/](https://sphinx-themes.org/) |
96 | | - |
97 | | -You will need to change at least these things to switch to the new template: |
98 | | - |
99 | | -- Install it and add it to the `requirements.txt` file (Sphinx templates come as a Python package) |
100 | | -- Update `conf.py`: |
101 | | - - `html_theme` variable to the selected theme |
102 | | - - update the `html_theme_options` to the available options of the theme |
103 | | - |
104 | | -Try for example the the [press theme](https://sphinx-themes.org/sample-sites/sphinx-press-theme/). |
105 | | -Don't forget to update the `html_theme_options` in `conf.py` to the available options of this theme. |
| 5 | +## Infos |
0 commit comments