pingou / centos / sig-guide

Forked from centos/sig-guide 2 years ago
Clone

Blame docs/documentation.md

2bd6f5
# Documentation
2bd6f5
2bd6f5
There is a possibility to also host your documentation under https://sigs.centos.org, following a workflow based on [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) (an enhanced version of [mkdocs](https://www.mkdocs.org/).  This SIG Guide is itself following the same workflow, built from .md files hosted in a git repository.
2bd6f5
2bd6f5
If you want to use the same workflow, proceed like this:
2bd6f5
2bd6f5
  * create a git repository somewhere (it can be hosted on centos infra - gitlab or pagure - but no limitation)
2bd6f5
  * locally test material for mkdocs (see below)
2bd6f5
  * create [CentOS Infra tracker issue](https://pagure.io/centos-infra/new_issue) that would contain the SIG name, public git url to clone/pull from
2bd6f5
  * once you commit to your upstream git project, it will be rendered in the next minutes and pushed to sigs.centos.org dedicated folder
2bd6f5
2bd6f5
## How to test locally material for mkdocs
2bd6f5
2bd6f5
The easiest way is just to use podman and a container:
2bd6f5
2bd6f5
```
2bd6f5
podman pull docker.io/squidfunk/mkdocs-material:latest
2bd6f5
```
2bd6f5
2bd6f5
Prepare your mkdocs.yml (see [ours](https://git.centos.org/centos/sig-guide/blob/master/f/mkdocs.yml) as quick reference and your `docs` folder containing your markdown (.md) files.
2bd6f5
Write documentation and once you have your skeleton, just test locally like this : 
2bd6f5
2bd6f5
```
2bd6f5
podman run --rm -it -p 8000:8000 -v ${PWD}:/docs:z squidfunk/mkdocs-material
2bd6f5
```
2bd6f5
2bd6f5
You can now open your browser to http://localhost:8000 and you'll be able to see live your edit/changes.
2bd6f5
Once happy, you can commit to git and see the rendered result in the next minutes going live
2bd6f5