ci-docs (#20)

Signed-off-by: Alexander Piskun <bigcat88@icloud.com>

.github/workflows/docs-check.yml

@@ -0,0 +1,20 @@
+name: Docs check
+on:
+  pull_request:
+
+jobs:
+  build_docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install Docs dependencies
+        run: python3 -m pip install ".[docs]"
+
+      - name: Build and push Docs
+        run: |
+          make html SPHINXOPTS="-W"

.github/workflows/docs.yml

@@ -0,0 +1,38 @@
+name: Docs
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  build_push_docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+
+      - name: Install Docs dependencies
+        run: python3 -m pip install ".[docs]"
+
+      - name: Build and push Docs
+        run: |
+          export CHANGES_DATE=`date -d"@$(git log -1 --pretty=%ct)" --iso-8601=seconds`
+          make html
+          git config --global user.name bigcat88
+          git config --global user.email "bigcat88@users.noreply.github.com"
+          docroot=`mktemp -d`
+          rsync -av "docs/_build/html/" "${docroot}/"
+          pushd "${docroot}"
+          git init
+          git remote add deploy "https://token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+          git checkout -b gh-pages
+          touch .nojekyll
+          git add .
+          msg="Docs: commit ${GITHUB_SHA} made on ${CHANGES_DATE} from ${GITHUB_REF} by ${GITHUB_ACTOR}"
+          git commit -am "${msg}"
+          git push deploy gh-pages --force
+          popd
+        env:
+          GITHUB_TOKEN: ${{ secrets.TOKEN_DOCS }}

Makefile

@@ -1,22 +1,12 @@
-build:
-	docker build --tag 'to_gif_dev' .
-
-start:
-	docker run --net=master_default --name=to_gif -p 9001:9001 to_gif_dev -e "app_name=to_gif"
-
-stop:
-	docker container stop to_gif
-
-register_app:
-	NEXTCLOUD_URL=http://nextcloud.local/index.php APP_ID=nc_py_api APP_VERSION=1.0.0 \
-	APP_SECRET=tC6vkwPhcppjMykD1r0n9NlI95uJMBYjs5blpIcA1PAdoPDmc5qoAjaBAkyocZ6E\
-	X1T8Pi+T5papEolTLxz3fJSPS8ffC4204YmggxPsbJdCkXHWNPHKWS9B+vTj2SIV APP_PORT=9002 \
-	python3 tests/_install.py
-
-remove:
-	docker rm to_gif
-
-all:
-	docker rm to_gif
-	docker build --tag 'to_gif_dev' .
-	docker run --net=master_default --name=to_gif -p 9001:9001 to_gif_dev
+.DEFAULT_GOAL := help
+
+.PHONY: doc
+.PHONY: html
+doc html:
+	$(MAKE) -C docs html
+
+.PHONY: help
+help:
+	@echo "Welcome to NC_PY_API development. Please use \`make <target>\` where <target> is one of"
+	@echo "  doc                make HTML docs"
+	@echo "  html               make HTML docs"

README.md

@@ -1,10 +1,12 @@
 # Official Nextcloud Python Framework
 
 [![Analysis & Coverage](https://github.com/cloud-py-api/nc_py_api/actions/workflows/analysis-coverage.yml/badge.svg)](https://github.com/cloud-py-api/nc_py_api/actions/workflows/analysis-coverage.yml)
+[![Docs](https://github.com/cloud-py-api/nc_py_api/actions/workflows/docs.yml/badge.svg)](https://cloud-py-api.github.io/nc_py_api/)
+[![codecov](https://codecov.io/github/cloud-py-api/nc_py_api/branch/main/graph/badge.svg?token=C91PL3FYDQ)](https://codecov.io/github/cloud-py-api/nc_py_api)
+
 ![PythonVersion](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)
 ![impl](https://img.shields.io/pypi/implementation/nc_py_api)
 ![pypi](https://img.shields.io/pypi/v/nc_py_api.svg)
-[![codecov](https://codecov.io/github/cloud-py-api/nc_py_api/branch/main/graph/badge.svg?token=C91PL3FYDQ)](https://codecov.io/github/cloud-py-api/nc_py_api)
 
 ### Remark
 

docs/Makefile

@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+PYTHON        = python3
+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
+
+github:
+	@make html
+	@cp -a build/html/. ./docs
+
+# 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/conf.py

@@ -0,0 +1,69 @@
+import os
+import sys
+from datetime import datetime
+
+import sphinx_rtd_theme
+
+dir_path = os.path.dirname(os.path.realpath(__file__))
+sys.path.insert(0, os.path.abspath(dir_path + "/_ext"))
+sys.path.insert(0, os.path.abspath("../."))
+
+import nc_py_api
+
+now = datetime.now()
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.extlinks",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+    "sphinx_inline_tabs",
+    "sphinx_issues",
+    "sphinx_rtd_theme"]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# General information about the project.
+project = "NcPyApi"
+copyright = str(now.year) + " Nextcloud GmbH"  # noqa
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = nc_py_api.__version__
+release = version
+
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+html_logo = "resources/logo.svg"
+
+html_theme_options = {
+    "display_version": True,
+}
+
+# If true, `todos` produce output, else they produce nothing.
+todo_include_todos = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# If true, Sphinx will warn about all references where the target cannot be found.
+# Default is False. You can activate this mode temporarily using the -n command-line
+# switch.
+nitpicky = True
+
+
+def setup(app):
+    app.add_js_file("js/script.js")
+    app.add_css_file("css/styles.css")
+    app.add_css_file("css/dark.css")
+    app.add_css_file("css/light.css")
+
+
+issues_github_path = "cloud-py-api/nc_py_api"

docs/index.rst

@@ -0,0 +1,5 @@
+====================
+Docs for the NcPyApi
+====================
+
+Welcome to the amazing docs that we will write for NcPyApi!