CMS Machine Learning Documentation

The documentation is located at cms-ml.github.io/documentation.

It is built with MkDocs using the material theme and support for PyMdown extensions. The pages are deployed with GitHub pages into the gh-pages branch of this repository, built through GitHub actions (see the gh-pages workflow). Images and other binary resources are versioned through Git LFS.

Build and serve locally

In a new python environment python -m venv venv && source venv/bin/activate run the following for installing the dependecies:

pip install mkdocs
pip install mkdocs-material
pip install pymdown-extensions
pip install mkdocs-minify-plugin
pip install mkdocs-markdownextradata-plugin
pip install mkdocs-include-markdown-plugin
pip install mkdocs-git-revision-date-localized-plugin
pip install termynal

You can then build the documentation locally via

mkdocs build --strict

which creates a directory site/ containing static HTML pages. To start a server to browse the pages, run

mkdocs serve --dev-addr localhost:8000

and open your webbrowser at http://localhost:8000. By default, all pages are automatically rebuilt and reloaded when a source file is updated.

To avoid installing the dependencies on your local machine, you can also use the dedicated cmsml/documentation docker image. Run

./docker/run.sh build

to build the documentation, and

./docker/run.sh serve [PORT]

to build and start the server process. Just as above, the default port is 8000 and updates of source files will automatically trigger the rebuilding and reloading of pages.

Development

• Source hosted at GitHub
• Report issues, questions, feature requests on GitHub Issues