---
# System prepended metadata

title: EasyBuild docs to mkdocs

---

# 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
```