# EasyBuild docs to mkdocs *(EasyBuild Zoom room: https://umu.zoom.us/j/561463243)* Goals: * rework current EasyBuild docs from `.rst` (Sphinx) to `.md` (with [MkDocs](https://www.mkdocs.org/) + [Material theme](https://squidfunk.github.io/mkdocs-material/)) * inspiration: https://docs.csc.fi (sources at https://github.com/CSCfi/csc-user-guide) * hosted on readthedocs.io or just pure GitHub (like easybuild-tutorial)? * leaning towards pure GitHub (one less site/service to worry about) * basic MkDocs site on readthedocs is already problematic?! (see https://readthedocs.org/projects/boegel-eb/builds/13457789/) * try to avoid broken links in https://easybuild.readthedocs.io + https://docs.easybuild.io * set up /en/latest subsite in `mkdocs` (cfr. https://docs.easybuild.io/en/latest/) * change pages on https://easybuild.readthedocs.io to just link to new docs *** ## Notes Ideas for meeting times (Kenneth in Belgium, Bennet in Detroit, Lev in Melbourne): * 10pm Belgium, 4pm Detroit, 6am Melbourne (+1h) * noon Belgium, 6am Detroit, 8pm Melbourne (+1-2h) * cfr. https://www.timeanddate.com/worldclock/meetingtime.html?year=2021&month=4&day=9&p1=1246&p2=179&p3=152 *** ## Planning ### Phase I (started March 2021) *(Kenneth, Bennet, Lev)* * start slow (structure + couple of pages) * look for opportunities to add notes, warnings, dropdowns (to reveal more details) * set up overall structure * empty pages for all pages in current documentation * to what extent can we leverage `pandoc`? * move docs into a separate repo? * https://github.com/easybuilders/easybuild-docs? * would make auto-deploy to GitHub Pages (without destroying EasyBuild website) easier... ### Phase II * search * open call for help, one page per person * more complex stuff * release notes * auto-generated docs (https://docs.easybuild.io/en/latest/version-specific/) * help from Miguel? ### Phase III * transition to new docs * avoid broken links in https://easybuild.readthedocs.io or https://docs.easybuild.io * switch over https://docs.easybuild.io to new docs *** ## First steps * setup: https://github.com/easybuilders/easybuild/tree/mkdocs * (TODO Kenneth) document `make` * (TODO Kenneth) set up auto-deploy on push (without breaking EasyBuild website!) * tasks * (TODO Kenneth) scripting to port pages from `.rst` to `.md` * document procedure to port a single page from `.rst` to `.md` * initial pages: * Terminology * https://docs.easybuild.io/en/latest/Concepts_and_Terminology.html * steal from https://easybuilders.github.io/easybuild-tutorial/2021-lust/terminology/ * Installation * reworked version of https://docs.easybuild.io/en/latest/Installation.html * steal from https://easybuilders.github.io/easybuild-tutorial/2021-lust/installation/ * first look: `pip install easybuild` + required modules tool * Configuration * old: https://docs.easybuild.io/en/latest/Configuration.html * steal from tutorial: https://easybuilders.github.io/easybuild-tutorial/2021-lust/configuration/ * configuration section for users and for site admins * Common things to change (e.g., don't put EB temp in possibly NFS home directory with small quota) * Workflow * running example of a simple package * old (WRF): https://docs.easybuild.io/en/latest/Typical_workflow_example_with_WRF.html * tutorial (no running example: https://easybuilders.github.io/easybuild-tutorial/2021-lust/basic_usage/ * Release notes * see https://github.com/boegel/easybuild/blob/mkdocs/docs.rst/Release_notes.rst * break up in smaller pages (one per release) * leverage `pandoc`? *** ## Structure (WIP) * Getting started * What is EasyBuild? * Terminology * Installation * Configuration *** ## mkdocs.yml ```yaml # TODO: ideas for mkdocs.yml contents example: foo: foo ```