Skip to content

Commit 5045b75

Browse files
ncdcncdc
authored
docs: various fixes (#355)
* Fix rendering issues with main docs page Fix indentation of bulleted lists so they render correctly. Fix some typos. Fix URL to roadmap. Signed-off-by: Andy Goldstein <[email protected]> * docs: fix roadmap link, nav links Signed-off-by: Andy Goldstein <[email protected]> * docs: various updates GH workflows: - Support manual triggering - Trigger on PRs to test site builds - Only trigger if docs-related files were changed - Switch to standard setup-python/pip caching - Add concurrency group Add 'make serve-docs' to build locally using a venv Freeze pip deps using requirements.txt Signed-off-by: Andy Goldstein <[email protected]> --------- Signed-off-by: Andy Goldstein <[email protected]>
1 parent 6770469 commit 5045b75

File tree

9 files changed

+385
-27
lines changed

9 files changed

+385
-27
lines changed

Diff for: ‎.github/workflows/pages.yaml

+33-11
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,46 @@
1-
name: Deploy Documentation site
1+
name: Build/Deploy Documentation
22
on:
3+
# So we can trigger manually if needed
4+
workflow_dispatch:
5+
6+
# To confirm any changes to docs build successfully, without deploying them
7+
pull_request:
8+
paths:
9+
- "docs/**"
10+
- ".github/workflows/pages.yaml"
11+
- "mkdocs.yml"
12+
13+
# Pushes to branches do the full build + deployment
314
push:
415
branches:
516
- main
17+
paths:
18+
- "docs/**"
19+
- ".github/workflows/pages.yaml"
20+
- "mkdocs.yml"
21+
622
permissions:
723
contents: write
24+
25+
# Don't allow multiple simultaneous instances because that would make deploying the docs nondeterministic
26+
concurrency:
27+
group: ${{ github.workflow }}
28+
829
jobs:
9-
deploy:
30+
docs:
1031
runs-on: ubuntu-latest
1132
steps:
1233
- uses: actions/checkout@v3
34+
1335
- uses: actions/setup-python@v4
1436
with:
1537
python-version: 3.x
16-
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
17-
- uses: actions/cache@v3
18-
with:
19-
key: mkdocs-material-${{ env.cache_id }}
20-
path: .cache
21-
restore-keys: |
22-
mkdocs-material-
23-
- run: pip install mkdocs-material
24-
- run: mkdocs gh-deploy --force
38+
cache: pip
39+
40+
# Deploy on merge
41+
- run: make deploy-docs
42+
if: github.event_name == 'push'
43+
44+
# Only build on everything else
45+
- run: make build-docs
46+
if: github.event_name != 'push'

Diff for: ‎.gitignore

+1-1
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,6 @@ install.sh
3636
.\#*
3737

3838
# documentation website asset folder
39-
docs/_site
39+
site
4040

4141
.tiltbuild/

Diff for: ‎Makefile

+23
Original file line numberDiff line numberDiff line change
@@ -243,3 +243,26 @@ deploy: manifests $(KUSTOMIZE) ## Deploy controller to the K8s cluster specified
243243
.PHONY: undeploy
244244
undeploy: ## Undeploy controller from the K8s cluster specified in ~/.kube/config. Call with ignore-not-found=true to ignore resource not found errors during deletion.
245245
$(KUSTOMIZE) build $(KUSTOMIZE_BUILD_DIR) | kubectl delete --ignore-not-found=$(ignore-not-found) -f -
246+
247+
248+
##@ Docs
249+
250+
VENVDIR=$(abspath docs/.venv)
251+
REQUIREMENTS_TXT=docs/requirements.txt
252+
253+
.PHONY: build-docs
254+
build-docs: venv
255+
. $(VENV)/activate; \
256+
mkdocs build
257+
258+
.PHONY: serve-docs
259+
serve-docs: venv
260+
. $(VENV)/activate; \
261+
mkdocs serve
262+
263+
.PHONY: deploy-docs
264+
deploy-docs: venv
265+
. $(VENV)/activate; \
266+
mkdocs gh-deploy --force
267+
268+
include Makefile.venv

Diff for: ‎Makefile.venv

+274
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,$@)

Diff for: ‎docs/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.venv

0 commit comments

Comments
 (0)