Ooo wondering if @aranas has thoughts on this bc she's looking into similar resources for clim-recal docs - alan-turing-institute/clim-recal#42 (comment)

I can help with this if you'd like... But I think you'd might want to go with MkDocs rather than Sphinx if we're working with markdown files, since the latter uses RST (Restructured Text) format, which is slightly different from markdown. You can use markdown in Sphinx as well, but it's not the native language.

IMHO, MkDocs is much more user-friendly and fitting for a first project like this!

Yes, I wanted to eventually use MkDocs for clim-recal as well, as Chris had recommended. @kallewesterling have you used it before and would be willing to give us a mini-workshop :)?

Yeah, sure!

@harisood let me know what you think - and if this aligns with what you had thought of!

yeah exactly right! Down for a mini workshop too

@kallewesterling have you used it before and would be willing to give us a mini-workshop :)?

I forgot to reply to this @aranas -- yes, I did work with MkDocs intensely about 2 years ago on this site. (see repo here: https://github.com/kallewesterling/django-app-documentation).

I'm sure there are new features etc but happy to read up on those.

100% to mini workshop!

Noting that specifically for the task described in this issue we should discuss how this site would add additional value vs. 1) existing documentation in TTW 2) documenting in this Github repo

Ooops! This mini workshop has completely dropped off my schedule. I could schedule one in for Dec 8 if folks are still interested?

Let me know @dingaaling @aranas @harisood !

Somehow I missed this whole discussion the first time but I’m very interested, Dec 8 sounds great!

wfm!

OK, I'll prepare something and keep you all in the loop!

I assume that all are familiar with Markdown.

I'm not, however, sure that you all have a full Python setup on your laptop. That's why I've provided some clear, concise instructions for the initial setup. It will ensure that all of you are is ready to dive into MkDocs during Dec 8.

Pre-Workshop Setup

1. Visual Studio Code (VS Code) Installation

If you haven't already, please download and install VS Code from https://code.visualstudio.com/.

Familiarize yourself with VS Code's basic features here.

2. Python Installation

MkDocs requires Python. If you don't have Python installed, download and install Python 3 from https://www.python.org/downloads/.

During installation, ensure you select the option to 'Add Python to PATH'.

If you run into any problem, just feel free to send me a message on Slack.

3. MkDocs Installation

Open VS Code's integrated terminal (from the "View" menu, select "Terminal").

Run the command: pip install mkdocs.

To confirm the installation, type mkdocs --version.

Create a Sample MkDocs Project

In the terminal, navigate to a directory where you want to create your test project. Then run mkdocs new test-project to create our little test set up.

Explore the generated test-project directory and familiarize yourself with its structure.

Additional resources that you may want to explore before we get started

• MkDocs Documentation: https://www.mkdocs.org/
• Markdown Guide: https://www.markdownguide.org/