Plan Autumn 2026

[mmesiti]

(Notes taken with Yu - this info needs also to be added to the exercise list)

• https://coderefinery.github.io/documentation/writing-readme-files/#exercise-have-fun-testing-some-readme-features as a walkthrough

Then:

• this https://coderefinery.github.io/documentation/writing-readme-files/#exercise-improve-the-readme-for-your-own-project or this https://coderefinery.github.io/documentation/writing-readme-files/#exercise-discuss-the-readme-of-a-project-that-you-use for exercise.

for those who have no own project or do not use a project with a public readme, we should have some links to public READMEs that are relevant to their scientific domains.

TODO: find these examples

as a walkthrough https://coderefinery.github.io/documentation/sphinx/#exercise-sphinx-quickstart

TODO: remove 'sphinx.ext.mathjax from the extension list in https://coderefinery.github.io/documentation/sphinx/#exercise-sphinx-and-latex, merge that exercise in "exercise-adding-more-sphinx-content"

• exercises:

https://coderefinery.github.io/documentation/sphinx/#exercise-adding-more-sphinx-content https://coderefinery.github.io/documentation/sphinx/#exercise-sphinx-and-latex https://coderefinery.github.io/documentation/sphinx/#exercise-sphinx-autodoc

This will be a walkthrough: https://coderefinery.github.io/documentation/gh_workflow/#exercise-deploy-sphinx-documentation-to-github-pages

https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site does this work?

Leading instructors for the walkthroughs:

• Michele for "Writing good README files" and "Sphinx and Markdown"
• Yu for "Deploying Shpinx Documentation to github pages" and "Hosting Websites/Homepages on GitHub pages"
• Michele Mesiti: Regarding "deploying sphinx docs to github pages"

quick demo using the web interface exercise session encouraging brave people to use git from the terminal review talking about github actions and the workflow file

TODO: reword the bit where it compares with previous episode and it says "We moved the documentation under /docs", because we did not move anything (this can be clear to some but also confusing to someone else)

as a demo/walkthrough: https://coderefinery.github.io/documentation/gh-pages/

TODO: reword

Written by humans

• Automatically generated documentation (e.g. API documentation) is useful as complementary documentation but it does not replace tutorials written by humans.

since AI can do some decent documentation writing (to be reviewed by humans, though)

Planned lead instructor/ main speaker:

• Motivation and wishlist: Yu
• Popular tools and solutions: Michele
• In-code documentation: Yu
• Writing good README files, Sphinx and md: Michele
• GitHub pages stuff: Yu

[mmesiti]

Time	What	Screen share	Lead	notes
13:00 - 13:10	Motivation and and wishlist	Michele	Yu and Michele	create a wishlist in collaborative notes
13:10 - 13:18	Popular tools and solutions	Michele	Michele
13:18 - 13:25	In-code documentation	Michele	Yu
13:25 - 13:30	Writing good README files	Michele	Michele & Yu	brief discussion
13:30 - 13:35	Walkthrough: README-1	Michele	Michele
13:35 - 13:45	README-2, README-3 (choose one or multiple) EXERCISE SESSION
13:45 - 13:50	Discussion of notes and README 2 and 3 exercises	Michele	Michele & Yu
13:50 - 14:00	Break
14:00 - 14:15	Sphinx and Markdown: Sphinx-1 (quickstart) as type along	Michele	Michele
14:15 - 14:35	Sphinx and Markdown: Sphinx-2/3/4 (adding more sphinx content) EXERCISE SESSION
14:35 - 14:40	Discussion	Michele	Michele & Yu
14:40 - 15:00	Sphinx deploy on GitHub pages (GH-Pages 1) WALKTHROUGH/CODE ALONG	Yu	Yu
15:00 - 15:10	Break
15:10 - 15:20	GH-Pages 2 as a walkthrough	Yu	Yu
15:20 - 15:30	Discussion, Summary	Yu	Yu & Michele

[mmesiti]

TODO: adjust times https://coderefinery.github.io/documentation/

[mmesiti]

sphinx quickstart 8.2.3 does not generate anymore "indices and tables" secion in index.rst (to double check)

[mmesiti]

remember to ask feedback about timing of exercises