Merge pull request #6 from antmicro/docs

Add docs generation

.github/docs-template/.gitignore

@@ -0,0 +1,3 @@
+build/
+*.pyc
+*.sw*

.github/docs-template/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

.github/docs-template/requirements.txt

@@ -0,0 +1 @@
+https://github.com/antmicro/antmicro-sphinx-utils/archive/main.zip

.github/docs-template/source/conf.py

@@ -0,0 +1,84 @@
+# -*- coding: utf-8 -*-
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Updated documentation of the configuration options is available at
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+from os import environ
+from datetime import datetime
+
+from antmicro_sphinx_utils.defaults import (
+    numfig_format,
+    extensions as default_extensions,
+    myst_enable_extensions as default_myst_enable_extensions,
+    myst_fence_as_directive as default_myst_fence_as_directive,
+    antmicro_html,
+    antmicro_latex
+)
+
+# -- General configuration -----------------------------------------------------
+
+# General information about the project.
+project = u'Protoplaster - docs example'
+basic_filename = 'protoplaster--docs-example'
+authors = u'Antmicro'
+copyright = f'{authors}, {datetime.now().year}'
+
+# The short X.Y version.
+version = ''
+# The full version, including alpha/beta/rc tags.
+release = ''
+
+# This is temporary before the clash between myst-parser and immaterial is fixed
+sphinx_immaterial_override_builtin_admonitions = False
+
+numfig = True
+
+# If you need to add extensions just add to those lists
+extensions = default_extensions
+myst_enable_extensions = default_myst_enable_extensions
+myst_fence_as_directive = default_myst_fence_as_directive
+
+myst_substitutions = {
+    "project": project
+}
+
+today_fmt = '%Y-%m-%d'
+
+todo_include_todos=False
+
+# -- Options for HTML output ---------------------------------------------------
+
+html_theme = 'sphinx_immaterial'
+
+html_last_updated_fmt = today_fmt
+
+html_show_sphinx = False
+
+html_title = project
+
+(
+    html_logo,
+    html_theme_options,
+    html_context
+) = antmicro_html(
+    gh_slug=environ.get('GITHUB_REPOSITORY', 'antmicro/protoplaster'),
+    pdf_url=f"{basic_filename}.pdf"
+)
+
+# -- Options for LaTeX output --------------------------------------------------
+
+(
+    latex_elements,
+    latex_documents,
+    latex_logo,
+    latex_additional_files
+) = antmicro_latex(basic_filename, authors, project)
+
+# -- Options for man output --------------------------------------------------
+
+man_pages = [
+    ('index', basic_filename, project,
+     [authors], 1)
+]

.github/docs-template/source/index.md

@@ -0,0 +1,9 @@
+# {{project}}
+
+```{toctree}
+:maxdepth: 2
+
+introduction
+readme
+protoplaster
+```

.github/docs-template/source/introduction.md

@@ -0,0 +1,8 @@
+# Introduction
+
+This documentation serves as an example of how individual projects documentation can look like.
+
+The second chapter contains information from the README file.
+
+The last chapter is generated from the sample ``test.yml`` file which can be found in the README.
+Its purpose is to demonstrate the documentation generated to describe test procedures used in a project.

.github/scripts/latex.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+
+set -e
+
+apt-get update -qq
+DEBIAN_FRONTEND=noninteractive apt-get -y install --no-install-recommends \
+  python3-pip \
+  python3-setuptools \
+  python3-wheel
+
+cd $(dirname $0)/../../docs
+
+pip3 install -r requirements.txt
+
+cd build/latex
+LATEXMKOPTS='-interaction=nonstopmode' make
+cp *.pdf ../html/

.github/scripts/sphinx.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env sh
+
+set -e
+
+cd $(dirname $0)/../../docs
+
+pip3 install -r requirements.txt
+
+make html latex

.github/workflows/docs.yml

@@ -0,0 +1,67 @@
+name: Generate and publish docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * 3'
+
+jobs:
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Get repository
+        uses: actions/checkout@v3
+
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - name: Install protoplaster with pip
+        run: |
+          pip install .
+
+      - name: Generate docs from yml
+        run: |
+          protoplaster -t tests/basic.yml --generate-docs
+
+      - name: Prepare docs template
+        run: |
+          cp -r .github/docs-template docs/
+          cp README.md docs/source/readme.md
+          cp protoplaster.rst docs/source/
+
+      - name: Build html
+        uses: docker://btdi/sphinx:min
+        with:
+          args: ./.github/scripts/sphinx.sh
+
+      - name: Build pdf
+        uses: docker://btdi/latex
+        with:
+          args: ./.github/scripts/latex.sh
+
+      - name: 'Upload artifact: Sphinx HTML and PDF'
+        uses: actions/upload-artifact@v3
+        with:
+          name: Documentation
+          path: docs/build/html
+
+      - name: Deploy
+        if: github.ref == 'refs/heads/main'
+        run: |
+          sudo chown -R $(whoami) docs
+          cd docs/build/html
+          touch .nojekyll
+          git init
+          cp ../../../.git/config ./.git/config
+          git add .
+          git config --local user.email "push@gha"
+          git config --local user.name "GHA"
+          git commit -am "update ${{ github.sha }}"
+          git push -u origin +HEAD:gh-pages
+          rm -rf .git

.gitignore

@@ -2,5 +2,6 @@ __pycache__/
 *.egg-info/
 *.egg
 build
+venv
 protoplaster/docs/test_*.rst
 protoplaster.rst