fix(openchallenges): restructure docs site

[vpchung]

Fixes #2430

Changelog

• Update categories to:
  • Home: overview of the monorepo, current supported tools/products
  • Getting Started: introduces the technologies involved and how to setup locally/remotely
  • Tutorials: walks user through how to develop, organized by product
  • Developers Guide: walks user through how to maintain and update the monorepo
  • Reference: list of classes/APIs/microservices, organized by product

To test locally

1. Install mkdocs, mkdocs-material, and termynal, ideally in a virtual environment, e.g.

   conda create -n docs python=3.12
   conda activate docs
   pip install mkdocs mkdocs-material termynal
   

2. Checkout this branch, then start the server:

   mkdocs serve
   

   This will serve the documentation on http://127.0.0.1:8000. If you get an error about the port already being used, stop the affected container:

   workspace-docker-stop
   

Once done, stop the server with Ctrl + C

Preview

More recent screenshots found in comment below

Home page

Getting Started

Tutorials

Developers Guide

Reference

[tschaffter]

Home page:

• the logos don't render in the markdown preview on GH
• the logos take a lot of space, including in the source of the file
  • replace by a table that include info about the project and link to the product space on the doc site?
• Tutorials
  • Split by programming languages or project type
  • This should contribute to developing reusable components instead of project-specific component
    • E.g. Creating a REST API in Python should be the same for Schematic or OpenChallenges
  • Types of projects:
    • Java:
      • library
      • REST API
    • Python
      • REST API
    • Angular
      • App
      • library
      • API client for Angular (is a library)
    • R
      • library
  • Docker-based project (e.g. openchallenges-mariadb)

[tschaffter]

@vpchung The proposed structure is already a nice improvement on the initial version. Feel free to use my feedback as you see fit and then merge when you are satisfied. I expect the structure of the docs to become clearer as we start curating its content.

[vpchung]

the logos don't render in the markdown preview on GH

I did not touch the main README for the repo, so no changes should be seen there. Nevermind, I misunderstood what you meant here.

replace by a table that include info about the project and link to the product space on the doc site?

Split by programming languages or project type

Sounds good.

[vpchung]

Feedback has been implemented:

[vpchung]

then merge when you are satisfied

@tschaffter I don't have the permission to force-merge without an approval. We can merge this after your return!

[tschaffter]

@vpchung How can this PR be tested?

[vpchung]

Thanks, added notes above to the description.