Plan Autumn 2026 #306
Description
(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
- 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