Merge pull request #40 from nfdi4cat/issue39-docs-skeleton

Add skeleton for gh-pages documentation with Sphinx

.editorconfig

@@ -0,0 +1,18 @@
+# Check http://editorconfig.org for more information
+# This is the main config file for this project:
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false

.github/ISSUE_TEMPLATE/nfdi4cat-central-data-repositry-issue-template--repo4cat-.md

@@ -1,6 +1,6 @@
 ---
-name: NFDI4Cat Central Data Repositry issue template (repo4cat)
-about: Template for issues related to NFDI4Cat Central Data Repository
+name: NFDI4Cat Central Data Repository issue template (repo4cat)
+about: Template for issues related to NFDI4Cat Central Data Repository and its Documentation
 title: ''
 labels: repo4cat
 assignees: ''

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+- package-ecosystem: github-actions
+  directory: "/"
+  schedule:
+    interval: monthly

.github/workflows/ci-pr.yml

@@ -0,0 +1,72 @@
+# This action runs when a pull request to main is created or updated
+# (but not when it is merged into main).
+
+name: CI on pull request create or update
+on:
+  pull_request_target:
+    branches:
+      - main
+    types: [opened, reopened, synchronize]
+  workflow_dispatch:
+
+env:
+  FORCE_COLOR: "1"  # Make tool output pretty.
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+  PIP_PROGRESS_BAR: "off"
+  LOGLEVEL: "DEBUG"
+  RUN_URL: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID
+
+jobs:
+  build_vocab:
+    name: Test build of documentation
+    # Run on all pull request types except merge which has its own workflow.
+    if: ${{ !github.event.pull_request.merged }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout PR branch into cwd
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          # Checkout the fork/head-repository to push changes to the fork.
+          # Without this the base repository will be checked out and committed to.
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+
+          # Checkout the branch made in the fork.
+          ref: ${{ github.head_ref }}
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -VV
+          python -m pip install --upgrade pip
+
+          # install tagged version
+          python -m pip install -r docs/requirements.txt
+
+XXX
+      - name: Set dynamic environment variables.
+        run: |
+          echo "RUN_DATE=$(date +'%Y-%m-%dT%H%M')" >> $GITHUB_ENV
+
+      - name: Build Sphinx documentation (website)
+        run: |
+          sphinx-build --nitpicky --fail-on-warning --keep-going docs docs/_build
+          cp -r docs/_build/. publish/
+
+
+      - name: Store publish dir (=pages) as artifact
+        # This step is not required and may be removed.
+        # It may be helpful for trouble shooting.
+        if: ${{ always() }}
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874
+        with:
+          name: docs-build-from-pull-request
+          path: publish/
+          retention-days: 5
+
+# Lit:
+# https://github.com/peaceiris/actions-gh-pages

.github/workflows/merge.yml

@@ -0,0 +1,89 @@
+# This action runs on merging of PR to main.
+#
+# Workflow steps:
+# - checkout gh-pages for updating
+# - create joined vocabulary file in addition to split version
+# - create excel-file from turtle
+# - build pyLODE docs
+# - build sphinx docs/site
+# - publish docs, vocabulary-turtle files and excel-file to gh-pages
+
+name: Build
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'vocabularies/**.ttl'
+  workflow_dispatch:
+
+env:
+  FORCE_COLOR: "1"  # Make tool output pretty.
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+  PIP_PROGRESS_BAR: "off"
+  LOGLEVEL: "DEBUG"
+
+jobs:
+  build:
+    name: Build documentation for gh-pages
+    permissions:
+      # Required for peaceiris/actions-gh-pages below
+      contents: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          # Using fetch-depth 0 is the only way to get all tags which are needed for building docs.
+          fetch-depth: 0
+
+      - name: Checkout gh-pages branch to dir publish/
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        with:
+          ref: gh-pages
+          path: publish
+          fetch-depth: 1
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -VV
+          python -m pip install --upgrade pip
+
+          # install tagged version
+          python -m pip install -r docs/requirements.txt
+
+      - name: Build Sphinx documentation (website)
+        run: |
+          sphinx-build --nitpicky --fail-on-warning --keep-going docs docs/_build
+          cp -r docs/_build/. publish/
+
+      - name: Deploy updated gh-pages content
+        # This replaces all prior content in gh-pages branch. But we have
+        # checked out the gh-pages branch above so that we keep all prior
+        # content and just re-publish the extended version.
+        # Pinning of action managed by dependabot
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e
+        if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./publish
+          force_orphan: true
+
+      - name: Store publish dir (=pages) as artifact
+        # This step is not required and may be removed.
+        # It may be helpful for trouble shooting.
+        if: ${{ always() }}
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874
+        with:
+          name: repo4cat-gh-pages-content
+          path: publish/
+          retention-days: 5
+
+# Lit:
+# https://github.com/peaceiris/actions-gh-pages

.gitignore

@@ -0,0 +1,94 @@
+# Jupyter Notebooks
+
+.ipynb_checkpoints
+*/.ipynb_checkpoints/*
+
+# Python - Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Sphinx documentation
+docs/_build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# VSCode project settings
+.vscode
+
+# Rope project settings
+.ropeproject
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# setuptools_scm generated version file
+_version.py
+
+# Excel/OpenOffice temporary files
+~$*
+.~*

.markdownlint.jsonc

@@ -0,0 +1,17 @@
+/*
+Configuration file for VSCode-markdownlint extension,
+see https://github.com/DavidAnson/vscode-markdownlint#configure
+
+For how the rules can be configured,
+see https://github.com/DavidAnson/markdownlint/blob/v0.35.0/schema/.markdownlint.jsonc
+*/
+{
+  "default": true,
+  "MD013": {
+    "line_length": 160  // Allow longer lines
+  },
+  "MD033": {
+    "allowed_elements": ["img"]  // Allow inline images
+  },
+  "MD034": false, // No bare URLs
+}

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+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)

docs/README.md

@@ -0,0 +1,7 @@
+# Guidelines and Maintenance Documentation
+
+We use [Sphinx](https://www.sphinx-doc.org/) as documentation builder with the [furo](https://github.com/pradyunsg/furo) theme
+and [MySt](https://mystmd.org/) to support extended markdown.
+
+To get an overview about the styling features supported visit the [furo theme documentation](https://pradyunsg.me/furo/kitchen-sink/)
+or the [MyST authoring documentation](https://mystmd.org/guide/typography).