Create knowledge commons pages - infrastructure choice

[cassgvp]

Summary of issue

A core part of our activites is to deliver a public facing knowledge commons where we can share materials and recieve community contribution.

Github pages is an apporpriate vehicle for this (more so than a Turing managed webpage, for example) as it we can be flexible and responsive in the content, and enable version controlled attribution of community input in the copy itself. Github issues will also be a valuable tool for receiving (and visibly responding to) community input.

We understand that the creation of github pages sites is acceptable to Turing comms and compliance teams under the proviso that we call it "pages" and not "website". RCM communications guidelines (in development) refer to them as "open source project pages".

Existing resources that we can "template" for infrastructure

• The Turing Way (Jupyter Book)
• Environmental Data Science Book (Jupyter Book)
• AIM-RSF Glossaries. (Jupyter book)
• Scivision
• Turing Commons
• RCM wiki (Quarto)
• Open WIN (github pages "just the docs" theme)
• TEDANA (read the docs)

To do

• Decide on which infrastructure to template (pros/cons)
• agree on some basic (first pass) content placeholders

pros/cons of infrastructure templates

• Jupyter books
  • Well used in TPS => more sustainable maintenance (cf Quarto)
  • Well used in TPS => consistency of experience in moving out community members into/from TTW

Content pages (for now!)

• Who are we - TRIC-DT Hub (identity, values, operating handbook, governance, roadmap)
• Who are we - community (stakeholders, narrative, personas, mountain of engagement - others from Open WIN)
• Get involved/connect with community (events)
• Reproducible DTs (specific areas linking into TTW best practice
• Benefits of working open
• Projects

[cassgvp]

In duscussion with @chrisdburr:

What features do we need from the project pages?

• zotero API integration? API can return a json of curated bibliography with java script to populate the website. Not sure if we can do this with jupyter books? Can you execute arbitrary java script and embed an html template? Looks like yes: https://jupyterbook.org/advanced/html.html
• book navigation
• search
• zenodo integration (achieveable with github)
• new html theme pages outside of the templates?
• server side rendering (e.g. for user authentication) - no. All authentication will be through github, otherwise we will be holding data etc.

Above all looks to be acheivable in jupyterbook.

@chrisdburr will confirm and look into extensibility of the static site.

@cassgvp will set up the github side of things (not the static site yet), framed as "TRIC-DT public repo, managed byt the Hub"

[chrisdburr]

Happy to report that the use cases I had in mind are either covered by the advanced HTML options (https://jupyterbook.org/en/stable/advanced/html.html) or can be done with fiddly but doable Sphinx customisation. So, all good from my side.

[kallewesterling]

In @chrisdburr's absence I'm happy to help out with the technical side of things, if you need @cassgvp.

[cassgvp]

Note to update the README with a link to the knowldege commons once that is public!

• Update README with knowledge commons link

[chrisdburr]

The JupyterBook is now created and scaffolded with the following tasks completed:

1. Structure of JB setup
2. Initial directories and pages created
3. GitHub action setup to publish to GitHub pages
4. Admonitions added to blank page to notify readers of work-in-progress

Currently, these changes are on the docs branch: https://github.com/alan-turing-institute/tric-dt/tree/docs/tric-dt-book

I would suggest we add a few more pages before merging the branch with main.