Create a proof of concept of the template repository for guides

[amercader]

Context

The School of Data team publishes several guides and reports in the context of different projects. The presentation format of these reports is generally PDF files, as well as the online versions. The process for generating these guides is currently one of:

• A designer manually creating a PDF (like the one linked on this page) from a source Google doc (like this one)
• Custom-made apps based on different apps, like:
  • Trainer's guide, built with Livemark
  • Curriculum website, built with Next.JS (older version built on Jekyll, another fork built on bookdown)

Both these approaches make the updating of guides complicated or impossible, and make collaboration difficult. The Scoda team would like to consolidate an approach which was more flexible and streamlined and made easier for collaborators to submit contributions.

Approach and requirements

The goal of this mini-project is to set up a pilot project, ideally re-using some existing published content that showcases the new approach and highlights its limitations so we can explore how to fix them.

As a starting point we are going to explore a repository of Markdown content files, which are built into an HTML site and a PDF document. For an initial phase we will use a documentation builder like Sphinx or MKDocs. If we find we need more advance functionality we can explore using more advanced static site generators.

Requirements:

• Easy replicable to different guides, and allowing customization between them (eg GitHub repo templates)
• Markdown based, as it's the most collaborator friendly format (eg if using sphinx use the MyST parser)
• Adding new content should be done via GitHub pull requests
• It needs to be able to generate a PDF version of the content, and importantly, that generated PDF needs to be customized (changing style, adding logos etc)
• The content should support translations, connecting to an external service like Transifex
• In the online version, the content needs to be searchable
• In the online version, ideally there should be the option of adding custom HTML content in some pages, including custom layouts or dynamic content powered by JS

Example

This is just a suggested starting point and can be tweaked:

1. Content Source: Markdown files (Standard markdown plus extensions)
2. Documentation builder: Sphinx or MKDocs
3. Custom Scoda / OKF theme
4. Automated deployment and Hosting: Readthedocs.org or self-hosted on Github pages or similar (using a custom schoolofdata.org or okfn.org domain)

[amercader]

@clombion @benhur07b Let me know if I didn't capture something important

[avdata99]

@amercader here my test with mkdocs

Static page with GitHub pages and mkdocs action: https://avdata99.github.io/test-mkdocs/
Repo: https://github.com/avdata99/test-mkdocs
A PDF was built as part of the page build process

We can prepate a GH template with this (it will require custom CSS as our OKF theme)
Not sure on how much we can style the PDF, I'll investigate

[avdata99]

Check of the current version after an update

• Easy replicable to different guides:
• Allowing customization: Custom CSS and JS can be defined
• Use as a GitHub template. The repo it's also a template (tested here)
• Markdown based
• Adding new content should be done via GitHub pull requests
• Able to generate a PDF version of the content: Automatically on each commit to main
• Generated PDF needs to be customized
  • changing style: There's a custom scss file for this
  • adding logos: The cover and back-cover page can be customized
• The content should support translations, connecting to an external service like Transifex
• In the online version, the content needs to be searchable: mkdocs include a search tool.
• In the online version, ideally there should be the option of adding custom HTML content in some pages, including custom layouts or dynamic content powered by JS

[avdata99]

Not sure in a service like Transifex will work.
It look like if we want several languages (for HTML and PDF) we will need to use separated files and
squidfunk/mkdocs-material#2346.

[avdata99]

Creating a first site+pdf documentation with our test template

Home site
https://avdata99.github.io/testing-mkdocs-multilang-template/

Step by step to get you multilingual documentation site done:
https://github.com/avdata99/testing-mkdocs-multilang-template/blob/main/step-by-step-template.md

English version

Spanish version

I propose to have a meeting to check and discuss this approach. If this is what we expect, we can make the final changes