Commit c530ecdb authored by Jorge Tardío Rubio's avatar Jorge Tardío Rubio
Browse files

Use docker images in gitlab registry

parent 2761e6f4
Pipeline #2534 passed with stages
in 59 seconds
......@@ -4,7 +4,7 @@ stages:
- pdfs
build_mkdocs:
image: jtr0/mkdocs-material
image: registry.gsi.upm.es/docs/mkdocs-material
stage: build
only:
- main
......@@ -17,7 +17,7 @@ build_mkdocs:
- data
pages:
image: jtr0/mkdocs-material
image: registry.gsi.upm.es/docs/mkdocs-material
stage: deploy
only:
- main
......
# Mkdocs Material template with pdf conversion through pandoc and Eisvogel LaTeX template
# Mkdocs Material template with pdf conversion through pandoc and Eisvogel LaTeX
[![pipeline status](https://lab.gsi.upm.es/docs/mkdocs-material/badges/main/pipeline.svg)](https://lab.gsi.upm.es/docs/mkdocs-material/-/commits/main)
......@@ -11,15 +11,27 @@ The purpose of this repository is to show a template to **document a project wit
### Deploy on localhost
1. Clone this repository `git clone https://lab.gsi.upm.es/docs/mkdocs-material` and detele git dependencies with `rm -rf .git` or create a new mkdocs project with `mkdocs new <name-project>` with the same structure and copy the folder `latex-templates` and the files `pdf_metadata.md` and `mkdocs.yml`.
2. Run in Docker with the image [jtr0/mkdocs-material](https://hub.docker.com/r/jtr0/mkdocs-material) (recommended because it has installed [mkdocs-pandoc-plugin](https://pypi.org/project/mkdocs-pandoc-plugin/) and [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin)) or the oficial image [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material/) to serve the docs:
2. Serve the docs running in Docker with the image [registry.gsi.upm.es/docs/mkdocs-material](https://lab.gsi.upm.es/docs/mkdocs-material/container_registry/) or [jtr0/mkdocs-material](https://hub.docker.com/r/jtr0/mkdocs-material) (recommended because it has installed [mkdocs-pandoc-plugin](https://pypi.org/project/mkdocs-pandoc-plugin/) and [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin)). Other option is to use the oficial image [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material/) but without pdf generator and it's neccesary to delete :
```bash
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs jtr0/mkdocs-material
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs registry.gsi.upm.es/docs/mkdocs-material
```
3. Open [http://localhost:8000/](http://localhost:8000/) in your browser.
### Build pdfs with pandoc and Eisvogel LaTeX template in local
1. Build public content with pandoc-plugin to combine all markdown files in one (site/docs.pdf.md):
```bash
docker run --rm -it -v ${PWD}:/docs -e ENABLE_PANDOC_EXPORT=1 registry.gsi.upm.es/docs/mkdocs-material build
```
2. Build pdf with pandoc and eisvogel LaTeX:
```bash
docker run --rm -it -v ${PWD}:/data jtr0/latex-pandoc /bin/bash -c 'cp -r /data/docs/imgs /imgs ; pandoc -N --template=eisvogel.latex --listings -V lang=en --from markdown --variable mainfont="DejaVuSerif" --variable sansfont="DejaVuSans" --variable monofont="DejaVuSansMono" --variable fontsize=12pt --variable version=2.0 /data/pdf_metadata.md /data/site/docs.pdf.md --pdf-engine=xelatex --toc -o /data/pdfs/eisvogel_template.pdf;'
```
### Deploy on GitLab Pages
1. Go to GitLab, select `Set CI/CD` and copy the content of `.gitlab-ci.yml`.
1. Go to GitLab, select `Set CI/CD` and copy the content of [`.gitlab-ci.yml`](.gitlab-ci.yml).
## Overview
......@@ -38,7 +50,7 @@ Download artifacts of pdfs: [https://lab.gsi.upm.es/docs/mkdocs-material/-/jobs/
![Material for Mkdocs](docs/imgs/web_page.png)
Accesible on: [https://docs.gsi.upm.es/docs/mkdocs-material](https://docs.gsi.upm.es/docs/mkdocs-material/)
Accesible on: [https://docs.gsi.upm.es/docs/mkdocs-material/](https://docs.gsi.upm.es/docs/mkdocs-material/)
### Mkdocs
[Mkdocs](https://www.mkdocs.org/) is a fast, simple and downright gorgeous static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration.
......@@ -55,51 +67,6 @@ Accesible on: [https://docs.gsi.upm.es/docs/mkdocs-material](https://docs.gsi.up
[Eisvogel](https://github.com/Wandmalfarbe/pandoc-latex-template) is a clean pandoc LaTeX template to convert your markdown files to PDF or LaTeX. It is designed for lecture notes and exercises with a focus on computer science. See the [custom templates variables](https://github.com/Wandmalfarbe/pandoc-latex-template#custom-template-variables).
## Installation
### Docker (recommended)
Use the image [jtr0/mkdocs-material](https://hub.docker.com/r/jtr0/mkdocs-material) or the oficial image [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material/) to serve, build or deploy the docs. Mount the folder where your mkdocs.yml resides as a volume into /docs:
- Start development server on [http://localhost:8000](http://localhost:8000):
```bash
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs jtr0/mkdocs-material
```
- Build documentation:
```bash
docker run --rm -it -v ${PWD}:/docs jtr0/mkdocs-material build
```
### Pip
- **Requirements**. Install requirements to run the docs:
```bash
pipenv lock --requirements
```
- **Pipenv**. Add packages to the project with Pipenv:
```bash
# Install pipenv
pip install pipenv
# Install a package for the project
pipenv install <package>
# Activate Virtual Env
pipenv shell
# Desactivate Virtual Env
exit
# Run a script in the virtual env
pipenv run python <script.py>
# Generate `requirements.txt`:
pipenv lock --requirements
```
## Plugins
By default, [mkdocs-minify-plugin](https://github.com/byrnereese/mkdocs-minify-plugin) and [mkdocs-redirects](https://github.com/datarobot/mkdocs-redirects) are installed in oficial docker image [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material/).
......@@ -110,7 +77,7 @@ Use [mkdocs-pandoc-plugin](https://pypi.org/project/mkdocs-pandoc-plugin/) and g
### mkdocs-git-revision-date-localized-plugin
Use [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin)
Use [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin) to enable displaying the date of the last git modification of a page.
## Deploy
......@@ -121,14 +88,15 @@ Use [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdoc
stages:
- build
- deploy
- pdfs
- pdfs
build_mkdocs:
image: jtr0/mkdocs-material:dev
image: registry.gsi.upm.es/docs/mkdocs-material
stage: build
only:
- main
script:
- export ENABLE_PANDOC_EXPORT=1
- mkdir data
- mkdocs build --verbose --site-dir data --no-directory-urls
artifacts:
......@@ -136,7 +104,7 @@ build_mkdocs:
- data
pages:
image: jtr0/mkdocs-material:prod
image: registry.gsi.upm.es/docs/mkdocs-material
stage: deploy
only:
- main
......@@ -169,18 +137,3 @@ generate_pdfs:
docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs squidfunk/mkdocs-material gh-deploy
```
## Generate pdfs with pandoc and latex
- Build images:
```bash
sh scripts/build_dockers.sh
```
- Generate pdfs:
```bash
sh scripts/pdf_local_generator.sh
```
# Example of eisvogel template generation
```
docker run --rm -it -v ${PWD}:/data jtr0/latex-pandoc pandoc -N --template=eisvogel.latex --listings -V lang=en --from markdown --variable mainfont="DejaVuSerif" --variable sansfont="DejaVuSans" --variable monofont="DejaVuSansMono" --variable fontsize=12pt --variable version=2.0 /data/pdf_metadata.md /data/site/docs.pdf.md --pdf-engine=xelatex --toc -o /data/eisvogel_template.pdf
```
......@@ -9,15 +9,27 @@ The purpose of this repository is to show a template **to document a project wit
### Deploy on localhost
1. Clone this repository `git clone https://lab.gsi.upm.es/docs/mkdocs-material` and detele git dependencies with `rm -rf .git` or create a new mkdocs project with `mkdocs new <name-project>` with the same structure and copy the folder `latex-templates` and the files `pdf_metadata.md` and `mkdocs.yml`.
2. Run in Docker with the image [jtr0/mkdocs-material](https://hub.docker.com/r/jtr0/mkdocs-material) (recommended because it has installed [mkdocs-pandoc-plugin](https://pypi.org/project/mkdocs-pandoc-plugin/) and [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin)) or the oficial image [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material/) to serve the docs:
2. Serve the docs running in Docker with the image [registry.gsi.upm.es/docs/mkdocs-material](https://lab.gsi.upm.es/docs/mkdocs-material/container_registry/) or [jtr0/mkdocs-material](https://hub.docker.com/r/jtr0/mkdocs-material) (recommended because it has installed [mkdocs-pandoc-plugin](https://pypi.org/project/mkdocs-pandoc-plugin/) and [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin)). Other option is to use the oficial image [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material/) but without pdf generator and it's neccesary to delete :
```bash
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs jtr0/mkdocs-material
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs registry.gsi.upm.es/docs/mkdocs-material
```
3. Open [http://localhost:8000/](http://localhost:8000/) in your browser.
### Build pdfs with pandoc and Eisvogel LaTeX template in local
1. Build public content with pandoc-plugin to combine all markdown files in one (site/docs.pdf.md):
```bash
docker run --rm -it -v ${PWD}:/docs -e ENABLE_PANDOC_EXPORT=1 registry.gsi.upm.es/docs/mkdocs-material build
```
2. Build pdf with pandoc and eisvogel LaTeX:
```bash
docker run --rm -it -v ${PWD}:/data jtr0/latex-pandoc /bin/bash -c 'cp -r /data/docs/imgs /imgs ; pandoc -N --template=eisvogel.latex --listings -V lang=en --from markdown --variable mainfont="DejaVuSerif" --variable sansfont="DejaVuSans" --variable monofont="DejaVuSansMono" --variable fontsize=12pt --variable version=2.0 /data/pdf_metadata.md /data/site/docs.pdf.md --pdf-engine=xelatex --toc -o /data/pdfs/eisvogel_template.pdf;'
```
### Deploy on GitLab Pages
1. Go to GitLab, select `Set CI/CD` and copy the content of `.gitlab-ci.yml`.
1. Go to GitLab, select `Set CI/CD` and copy the content of [`.gitlab-ci.yml`](.gitlab-ci.yml).
## Overview
......@@ -33,7 +45,7 @@ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs jtr0/mkdocs-material
Download artifacts of pdfs: [https://lab.gsi.upm.es/docs/mkdocs-material/-/jobs/artifacts/main/download?job=generate_pdfs](https://lab.gsi.upm.es/docs/mkdocs-material/-/jobs/artifacts/main/download?job=generate_pdfs)
## Web page
### Web page
![Material for Mkdocs](imgs/web_page.png)
......@@ -54,53 +66,6 @@ Accesible on: [https://docs.gsi.upm.es/docs/mkdocs-material](https://docs.gsi.up
[Eisvogel](https://github.com/Wandmalfarbe/pandoc-latex-template) is a clean pandoc LaTeX template to convert your markdown files to PDF or LaTeX. It is designed for lecture notes and exercises with a focus on computer science. See the [custom templates variables](https://github.com/Wandmalfarbe/pandoc-latex-template#custom-template-variables).
## Installation
### Docker (recommended)
Use the image jtr0/mkdocs-material or the oficial image [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material/) to serve, build or deploy the docs. Mount the folder where your mkdocs.yml resides as a volume into /docs:
- Start development server on [http://localhost:8000](http://localhost:8000):
```bash
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
```
- Build documentation:
```bash
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build
```
### Pip
- **Requirements**. Install requirements to run the docs:
```bash
pipenv lock --requirements
```
- **Pipenv**. Add packages to the project with Pipenv:
```bash
# Install pipenv
pip install pipenv
# Install a package for the project
pipenv install <package>
# Activate Virtual Env
pipenv shell
# Desactivate Virtual Env
exit
# Run a script in the virtual env
pipenv run python <script.py>
# Generate `requirements.txt`:
pipenv lock --requirements
```
## Plugins
By default, [mkdocs-minify-plugin](https://github.com/byrnereese/mkdocs-minify-plugin) and [mkdocs-redirects](https://github.com/datarobot/mkdocs-redirects) are installed in oficial docker image [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material/).
......@@ -109,11 +74,9 @@ By default, [mkdocs-minify-plugin](https://github.com/byrnereese/mkdocs-minify-p
Use [mkdocs-pandoc-plugin](https://pypi.org/project/mkdocs-pandoc-plugin/) and generate a pdf or other output with pandoc. Active the opction with the environmental variable `ENABLE_PANDOC_EXPORT` set to 1.
### mkdocs-git-revision-date-localized-plugin
Use [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin)
Use [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin) to enable displaying the date of the last git modification of a page.
## Deploy
......@@ -124,14 +87,15 @@ Use [mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdoc
stages:
- build
- deploy
- pdfs
- pdfs
build_mkdocs:
image: jtr0/mkdocs-material:dev
image: registry.gsi.upm.es/docs/mkdocs-material
stage: build
only:
- main
script:
- export ENABLE_PANDOC_EXPORT=1
- mkdir data
- mkdocs build --verbose --site-dir data --no-directory-urls
artifacts:
......@@ -139,7 +103,7 @@ build_mkdocs:
- data
pages:
image: jtr0/mkdocs-material:prod
image: registry.gsi.upm.es/docs/mkdocs-material
stage: deploy
only:
- main
......@@ -165,34 +129,9 @@ generate_pdfs:
- public/pdfs/
```
### GitHub Pages
- Deploy documentation to GitHub Pages (not tested):
```bash
docker run --rm -it -v ~/.ssh:/root/.ssh -v ${PWD}:/docs squidfunk/mkdocs-material gh-deploy
```
## Generate pdfs with pandoc and latex
- Build images:
```bash
sh scripts/build_dockers.sh
```
- Generate pdfs:
```bash
sh scripts/pdf_local_generator.sh
```
### Example of eisvogel template
```
docker run --rm -it -v ${PWD}:/data jtr0/latex-pandoc pandoc -N --template=eisvogel.latex --listings -V lang=en --from markdown --variable mainfont="DejaVuSerif" --variable sansfont="DejaVuSans" --variable monofont="DejaVuSansMono" --variable fontsize=12pt --variable version=2.0 /data/pdf_metadata.md /data/site/docs.pdf.md --pdf-engine=xelatex --toc -o /data/eisvogel_template.pdf
```
- [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
- [ ] Vestibulum convallis sit amet nisi a tincidunt
* [x] In hac habitasse platea dictumst
* [x] In scelerisque nibh non dolor mollis congue sed et metus
* [ ] Praesent sed risus massa
- [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
#!/bin/sh
docker build --file dockerfiles/mkdocs-material+plugins.Dockerfile -t jtr0/mkdocs-material .
docker build -f dockerfiles/mkdocs-material+plugins.Dockerfile -t registry.gsi.upm.es/docs/mkdocs-material .
docker build --file dockerfiles/latex-pandoc.Dockerfile -t jtr0/latex-pandoc .
#!/bin/sh
# Push docker image to gitlab registry
docker push registry.gsi.upm.es/docs/mkdocs-material
\ No newline at end of file
#!/bin/sh
# Build public content with pandoc-plugin to combine markdown files
docker run --rm -it -v ${PWD}:/docs -e ENABLE_PANDOC_EXPORT=1 jtr0/mkdocs-material build
docker run --rm -it -v ${PWD}:/docs -e ENABLE_PANDOC_EXPORT=1 registry.gsi.upm.es/docs/mkdocs-material build
# Generate templates pdfs
docker run --rm -it -v ${PWD}:/data jtr0/latex-pandoc /bin/bash -c 'cp -r /data/docs/imgs /imgs ; pandoc -N --template=eisvogel.latex --listings -V lang=en --from markdown --variable mainfont="DejaVuSerif" --variable sansfont="DejaVuSans" --variable monofont="DejaVuSansMono" --variable fontsize=12pt --variable version=2.0 /data/pdf_metadata.md /data/site/docs.pdf.md --pdf-engine=xelatex --toc -o /data/pdfs/eisvogel_template.pdf; pandoc -N --template=pandoc-scholar.latex --listings -V lang=en --from markdown --variable mainfont="DejaVuSerif" --variable sansfont="DejaVuSans" --variable monofont="DejaVuSansMono" --variable fontsize=12pt --variable version=2.0 /data/pdf_metadata.md /data/site/docs.pdf.md --pdf-engine=xelatex --toc -o /data/pdfs/pandoc-scholar_template.pdf; pandoc -N --template=default.latex --listings -V lang=en --from markdown --variable mainfont="DejaVuSerif" --variable sansfont="DejaVuSans" --variable monofont="DejaVuSansMono" --variable fontsize=12pt --variable version=2.0 /data/pdf_metadata.md /data/site/docs.pdf.md --pdf-engine=xelatex --toc -o /data/pdfs/default_template.pdf'
#!/bin/sh
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs jtr0/mkdocs-material
\ No newline at end of file
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs registry.gsi.upm.es/docs/mkdocs-material
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment