Set up Read the Docs/Hugo site for RAM resources

harisood commented 9 months ago

Summary

J a thought I have, a way to render any MarkDown resources we create in a bit more of a professional way, e.g. as done with SATRE.

A skill I kinda want to learn too and may be useful for RAMs to pick up!

What needs to be done?

[ ] Setup this repo to render as a readthedocs or similar site

Who can help?

If we agree it's a good idea, poss something @aranas @kallewesterling @f-rower might want to help with?

Updates

[Replace this sentence to provide a status summary after the issue has been opened. To avoid others from reading through the full thread of comments, please share updates (e.g. decisions taken) regularly.]

dingaaling commented 9 months ago

Ooo wondering if @aranas has thoughts on this bc she's looking into similar resources for clim-recal docs - https://github.com/alan-turing-institute/clim-recal/issues/42#issuecomment-1673057414

kallewesterling commented 9 months ago

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!

aranas commented 9 months ago

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 :)?

kallewesterling commented 9 months ago

Yeah, sure!

kallewesterling commented 9 months ago

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

harisood commented 9 months ago

yeah exactly right! Down for a mini workshop too

kallewesterling commented 9 months ago

@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.

dingaaling commented 9 months ago

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

kallewesterling commented 5 months ago

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 !

aldenc commented 5 months ago

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

harisood commented 5 months ago

wfm!

kallewesterling commented 5 months ago

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

kallewesterling commented 5 months ago

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/

alan-turing-institute / research-application-management