Skip to content

Commit ca40605

Browse files
kcp-ci-botkcp-ci-bot
authored
Merge pull request #58 from embik/docs
Add mkdocs documentation (docs.kcp.io/kcp-operator)
2 parents 5e2a393 + 246bc25 commit ca40605

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+1477
-107
lines changed

‎.github/workflows/docs-gen-and-push.yaml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Documentation
2+
3+
on:
4+
# So we can trigger manually if needed
5+
workflow_dispatch:
6+
# To confirm any changes to docs build successfully, without deploying them
7+
pull_request:
8+
# Pushes to branches do the full build + deployment
9+
push:
10+
branches:
11+
- main
12+
- "release-*"
13+
paths:
14+
- "docs/**"
15+
- "sdk/apis/**"
16+
- ".github/workflows/docs-gen-and-push.yaml"
17+
18+
permissions:
19+
contents: write
20+
21+
concurrency:
22+
group: ${{ github.workflow }}
23+
24+
jobs:
25+
generate-and-push:
26+
name: Generate and push
27+
runs-on: ubuntu-latest
28+
steps:
29+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # tag=v4.2.2
30+
31+
- run: git fetch origin gh-pages
32+
- run: git fetch origin '+refs/tags/v*:refs/tags/v*' --no-tags
33+
34+
- uses: actions/setup-go@0aaccfd150d50ccaeb58ebd88d36e91967a5f35b # tag=v5.4.0
35+
with:
36+
go-version: v1.24.3
37+
cache: true
38+
39+
- uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 #tag=v5.5.0
40+
with:
41+
python-version: '3.10'
42+
cache: 'pip'
43+
44+
# mike does not support giving CLI flags for mkdocs, but we also do not
45+
# want to permanently enable strict mode, so here we enable it just for this
46+
# task
47+
- run: |
48+
echo "strict: true" >> docs/mkdocs.yml
49+
50+
- run: make generate-api-docs deploy-docs

‎Makefile‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -206,3 +206,25 @@ openshift-goimports: $(OPENSHIFT_GOIMPORTS) ## Download openshift-goimports loca
206206
.PHONY: $(OPENSHIFT_GOIMPORTS)
207207
$(OPENSHIFT_GOIMPORTS):
208208
@GO_MODULE=true hack/download-tool.sh github.com/openshift-eng/openshift-goimports openshift-goimports $(OPENSHIFT_GOIMPORTS_VER)
209+
210+
##@ Documentation
211+
212+
VENVDIR=$(abspath docs/venv)
213+
REQUIREMENTS_TXT=docs/requirements.txt
214+
215+
.PHONY: generate-api-docs
216+
generate-api-docs: ## Generate api docs from CRDs.
217+
git clean -fdX docs/content/reference
218+
docs/generators/crd-ref/run-crd-ref-gen.sh
219+
220+
.PHONY: local-docs
221+
local-docs: venv ## Serve documentation locally.
222+
. $(VENV)/activate; \
223+
VENV=$(VENV) cd docs && mkdocs serve
224+
225+
.PHONY: deploy-docs
226+
deploy-docs: venv ## Deploy documentation (CI make target).
227+
. $(VENV)/activate; \
228+
REMOTE=$(REMOTE) BRANCH=$(BRANCH) docs/scripts/deploy-docs.sh
229+
230+
include Makefile.venv

‎Makefile.venv‎

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
#
2+
# SEAMLESSLY MANAGE PYTHON VIRTUAL ENVIRONMENT WITH A MAKEFILE
3+
#
4+
# https://github.com/sio/Makefile.venv v2022.07.20
5+
#
6+
#
7+
# Insert `include Makefile.venv` at the bottom of your Makefile to enable these
8+
# rules.
9+
#
10+
# When writing your Makefile use '$(VENV)/python' to refer to the Python
11+
# interpreter within virtual environment and '$(VENV)/executablename' for any
12+
# other executable in venv.
13+
#
14+
# This Makefile provides the following targets:
15+
# venv
16+
# Use this as a dependency for any target that requires virtual
17+
# environment to be created and configured
18+
# python, ipython
19+
# Use these to launch interactive Python shell within virtual environment
20+
# shell, bash, zsh
21+
# Launch interactive command line shell. "shell" target launches the
22+
# default shell Makefile executes its rules in (usually /bin/sh).
23+
# "bash" and "zsh" can be used to refer to the specific desired shell.
24+
# show-venv
25+
# Show versions of Python and pip, and the path to the virtual environment
26+
# clean-venv
27+
# Remove virtual environment
28+
# $(VENV)/executable_name
29+
# Install `executable_name` with pip. Only packages with names matching
30+
# the name of the corresponding executable are supported.
31+
# Use this as a lightweight mechanism for development dependencies
32+
# tracking. E.g. for one-off tools that are not required in every
33+
# developer's environment, therefore are not included into
34+
# requirements.txt or setup.py.
35+
# Note:
36+
# Rules using such target or dependency MUST be defined below
37+
# `include` directive to make use of correct $(VENV) value.
38+
# Example:
39+
# codestyle: $(VENV)/pyflakes
40+
# $(VENV)/pyflakes .
41+
# See `ipython` target below for another example.
42+
#
43+
# This Makefile can be configured via following variables:
44+
# PY
45+
# Command name for system Python interpreter. It is used only initially to
46+
# create the virtual environment
47+
# Default: python3
48+
# REQUIREMENTS_TXT
49+
# Space separated list of paths to requirements.txt files.
50+
# Paths are resolved relative to current working directory.
51+
# Default: requirements.txt
52+
#
53+
# Non-existent files are treated as hard dependencies,
54+
# recipes for creating such files must be provided by the main Makefile.
55+
# Providing empty value (REQUIREMENTS_TXT=) turns off processing of
56+
# requirements.txt even when the file exists.
57+
# SETUP_PY
58+
# Space separated list of paths to setup.py files.
59+
# Corresponding packages will be installed into venv in editable mode
60+
# along with all their dependencies
61+
# Default: setup.py
62+
#
63+
# Non-existent and empty values are treated in the same way as for REQUIREMENTS_TXT.
64+
# WORKDIR
65+
# Parent directory for the virtual environment.
66+
# Default: current working directory.
67+
# VENVDIR
68+
# Python virtual environment directory.
69+
# Default: $(WORKDIR)/.venv
70+
#
71+
# This Makefile was written for GNU Make and may not work with other make
72+
# implementations.
73+
#
74+
#
75+
# Copyright (c) 2019-2020 Vitaly Potyarkin
76+
#
77+
# Licensed under the Apache License, Version 2.0
78+
# <http://www.apache.org/licenses/LICENSE-2.0>
79+
#
80+
81+
82+
#
83+
# Configuration variables
84+
#
85+
86+
WORKDIR?=.
87+
VENVDIR?=$(WORKDIR)/.venv
88+
REQUIREMENTS_TXT?=$(wildcard requirements.txt) # Multiple paths are supported (space separated)
89+
SETUP_PY?=$(wildcard setup.py) # Multiple paths are supported (space separated)
90+
SETUP_CFG?=$(foreach s,$(SETUP_PY),$(wildcard $(patsubst %setup.py,%setup.cfg,$(s))))
91+
MARKER=.initialized-with-Makefile.venv
92+
93+
94+
#
95+
# Python interpreter detection
96+
#
97+
98+
_PY_AUTODETECT_MSG=Detected Python interpreter: $(PY). Use PY environment variable to override
99+
100+
ifeq (ok,$(shell test -e /dev/null 2>&1 && echo ok))
101+
NULL_STDERR=2>/dev/null
102+
else
103+
NULL_STDERR=2>NUL
104+
endif
105+
106+
ifndef PY
107+
_PY_OPTION:=python3
108+
ifeq (ok,$(shell $(_PY_OPTION) -c "print('ok')" $(NULL_STDERR)))
109+
PY=$(_PY_OPTION)
110+
endif
111+
endif
112+
113+
ifndef PY
114+
_PY_OPTION:=$(VENVDIR)/bin/python
115+
ifeq (ok,$(shell $(_PY_OPTION) -c "print('ok')" $(NULL_STDERR)))
116+
PY=$(_PY_OPTION)
117+
$(info $(_PY_AUTODETECT_MSG))
118+
endif
119+
endif
120+
121+
ifndef PY
122+
_PY_OPTION:=$(subst /,\,$(VENVDIR)/Scripts/python)
123+
ifeq (ok,$(shell $(_PY_OPTION) -c "print('ok')" $(NULL_STDERR)))
124+
PY=$(_PY_OPTION)
125+
$(info $(_PY_AUTODETECT_MSG))
126+
endif
127+
endif
128+
129+
ifndef PY
130+
_PY_OPTION:=py -3
131+
ifeq (ok,$(shell $(_PY_OPTION) -c "print('ok')" $(NULL_STDERR)))
132+
PY=$(_PY_OPTION)
133+
$(info $(_PY_AUTODETECT_MSG))
134+
endif
135+
endif
136+
137+
ifndef PY
138+
_PY_OPTION:=python
139+
ifeq (ok,$(shell $(_PY_OPTION) -c "print('ok')" $(NULL_STDERR)))
140+
PY=$(_PY_OPTION)
141+
$(info $(_PY_AUTODETECT_MSG))
142+
endif
143+
endif
144+
145+
ifndef PY
146+
define _PY_AUTODETECT_ERR
147+
Could not detect Python interpreter automatically.
148+
Please specify path to interpreter via PY environment variable.
149+
endef
150+
$(error $(_PY_AUTODETECT_ERR))
151+
endif
152+
153+
154+
#
155+
# Internal variable resolution
156+
#
157+
158+
VENV=$(VENVDIR)/bin
159+
EXE=
160+
# Detect windows
161+
ifeq (win32,$(shell $(PY) -c "import __future__, sys; print(sys.platform)"))
162+
VENV=$(VENVDIR)/Scripts
163+
EXE=.exe
164+
endif
165+
166+
touch=touch $(1)
167+
ifeq (,$(shell command -v touch $(NULL_STDERR)))
168+
# https://ss64.com/nt/touch.html
169+
touch=type nul >> $(subst /,\,$(1)) && copy /y /b $(subst /,\,$(1))+,, $(subst /,\,$(1))
170+
endif
171+
172+
RM?=rm -f
173+
ifeq (,$(shell command -v $(firstword $(RM)) $(NULL_STDERR)))
174+
RMDIR:=rd /s /q
175+
else
176+
RMDIR:=$(RM) -r
177+
endif
178+
179+
180+
#
181+
# Virtual environment
182+
#
183+
184+
.PHONY: venv
185+
venv: $(VENV)/$(MARKER)
186+
187+
.PHONY: clean-venv
188+
clean-venv:
189+
-$(RMDIR) "$(VENVDIR)"
190+
191+
.PHONY: show-venv
192+
show-venv: venv
193+
@$(VENV)/python -c "import sys; print('Python ' + sys.version.replace('\n',''))"
194+
@$(VENV)/pip --version
195+
@echo venv: $(VENVDIR)
196+
197+
.PHONY: debug-venv
198+
debug-venv:
199+
@echo "PATH (Shell)=$$PATH"
200+
@$(MAKE) --version
201+
$(info PATH (GNU Make)="$(PATH)")
202+
$(info SHELL="$(SHELL)")
203+
$(info PY="$(PY)")
204+
$(info REQUIREMENTS_TXT="$(REQUIREMENTS_TXT)")
205+
$(info SETUP_PY="$(SETUP_PY)")
206+
$(info SETUP_CFG="$(SETUP_CFG)")
207+
$(info VENVDIR="$(VENVDIR)")
208+
$(info VENVDEPENDS="$(VENVDEPENDS)")
209+
$(info WORKDIR="$(WORKDIR)")
210+
211+
212+
#
213+
# Dependencies
214+
#
215+
216+
ifneq ($(strip $(REQUIREMENTS_TXT)),)
217+
VENVDEPENDS+=$(REQUIREMENTS_TXT)
218+
endif
219+
220+
ifneq ($(strip $(SETUP_PY)),)
221+
VENVDEPENDS+=$(SETUP_PY)
222+
endif
223+
ifneq ($(strip $(SETUP_CFG)),)
224+
VENVDEPENDS+=$(SETUP_CFG)
225+
endif
226+
227+
$(VENV):
228+
$(PY) -m venv $(VENVDIR)
229+
$(VENV)/python -m pip install --upgrade pip setuptools wheel
230+
231+
$(VENV)/$(MARKER): $(VENVDEPENDS) | $(VENV)
232+
ifneq ($(strip $(REQUIREMENTS_TXT)),)
233+
$(VENV)/pip install $(foreach path,$(REQUIREMENTS_TXT),-r $(path))
234+
endif
235+
ifneq ($(strip $(SETUP_PY)),)
236+
$(VENV)/pip install $(foreach path,$(SETUP_PY),-e $(dir $(path)))
237+
endif
238+
$(call touch,$(VENV)/$(MARKER))
239+
240+
241+
#
242+
# Interactive shells
243+
#
244+
245+
.PHONY: python
246+
python: venv
247+
exec $(VENV)/python
248+
249+
.PHONY: ipython
250+
ipython: $(VENV)/ipython
251+
exec $(VENV)/ipython
252+
253+
.PHONY: shell
254+
shell: venv
255+
. $(VENV)/activate && exec $(notdir $(SHELL))
256+
257+
.PHONY: bash zsh
258+
bash zsh: venv
259+
. $(VENV)/activate && exec $@
260+
261+
262+
#
263+
# Commandline tools (wildcard rule, executable name must match package name)
264+
#
265+
266+
ifneq ($(EXE),)
267+
$(VENV)/%: $(VENV)/%$(EXE) ;
268+
.PHONY: $(VENV)/%
269+
.PRECIOUS: $(VENV)/%$(EXE)
270+
endif
271+
272+
$(VENV)/%$(EXE): $(VENV)/$(MARKER)
273+
$(VENV)/pip install --upgrade $*
274+
$(call touch,$@)

0 commit comments

Comments
 (0)