From 5fecc89bb347e73a8836314eb175c69a26c4183c Mon Sep 17 00:00:00 2001 From: Toni Kangas Date: Mon, 23 Dec 2024 11:17:51 +0200 Subject: [PATCH] chore: use `mdtest normalise` to prepare examples for mkdocs (#347) --- .ci/docs/prepare_info_texts_for_mkdocs.py | 31 ------------------- .ci/tools/go.mod | 18 ++++++++++++ .ci/tools/go.sum | 36 +++++++++++++++++++++++ .ci/tools/tools.go | 8 +++++ Makefile | 7 +++-- 5 files changed, 67 insertions(+), 33 deletions(-) delete mode 100755 .ci/docs/prepare_info_texts_for_mkdocs.py create mode 100644 .ci/tools/go.mod create mode 100644 .ci/tools/go.sum create mode 100644 .ci/tools/tools.go diff --git a/.ci/docs/prepare_info_texts_for_mkdocs.py b/.ci/docs/prepare_info_texts_for_mkdocs.py deleted file mode 100755 index 27c0b27c2..000000000 --- a/.ci/docs/prepare_info_texts_for_mkdocs.py +++ /dev/null @@ -1,31 +0,0 @@ -'''Prepare info texts for mkdocs - -This script overwrites code fences in the .md files copied into docs/examples so that only language and title are left in-place, because mkdocs (and the used theme) has limited support for fenced code-block info texts. -''' -import fileinput -import os -import re -import sys - -def get_markdown_files(path): - return (f.path for f in os.scandir(path) if f.name.endswith('.md')) - -def simplify_info_texts(path): - for line in fileinput.input(path, inplace=True): - if line.startswith('```'): - start = re.search(r'^```[a-zA-Z]*', line) - title = re.search(r'title=".*"', line) - - old = line.rstrip('\n') - new = f'{start.group(0)} {title.group(0)}' if title else f'{start.group(0)}' - - if new != old: - sys.stderr.write(f'{fileinput.filename()}:{fileinput.filelineno()}:\n- {old}\n+ {new}\n') - print(new) - else: - print(line, end='') - -if __name__ == '__main__': - files = get_markdown_files('docs/examples/') - for f in files: - simplify_info_texts(f) diff --git a/.ci/tools/go.mod b/.ci/tools/go.mod new file mode 100644 index 000000000..a8745682b --- /dev/null +++ b/.ci/tools/go.mod @@ -0,0 +1,18 @@ +module github.com/UpCloudLtd/upcloud-cli/tools + +go 1.23.2 + +require github.com/UpCloudLtd/mdtest v0.0.0-20241218095607-687f26589c4c + +require ( + github.com/UpCloudLtd/progress v1.0.3 // indirect + github.com/inconshreveable/mousetrap v1.1.0 // indirect + github.com/jedib0t/go-pretty/v6 v6.6.5 // indirect + github.com/mattn/go-runewidth v0.0.16 // indirect + github.com/rivo/uniseg v0.4.7 // indirect + github.com/spf13/cobra v1.8.1 // indirect + github.com/spf13/pflag v1.0.5 // indirect + golang.org/x/sys v0.28.0 // indirect + golang.org/x/term v0.27.0 // indirect + golang.org/x/text v0.21.0 // indirect +) diff --git a/.ci/tools/go.sum b/.ci/tools/go.sum new file mode 100644 index 000000000..9a1fa6879 --- /dev/null +++ b/.ci/tools/go.sum @@ -0,0 +1,36 @@ +github.com/UpCloudLtd/mdtest v0.0.0-20241218095607-687f26589c4c h1:tJD6Sm3pKMySNSCZCySYwx76f713vVHjnCJWDbDLYwE= +github.com/UpCloudLtd/mdtest v0.0.0-20241218095607-687f26589c4c/go.mod h1:bb9tb8kvg8INEgPFulXaqHGbyIjxNsqVWF2wy6X7G9Q= +github.com/UpCloudLtd/progress v1.0.3 h1:8SfntHkBPyQc5BL3946Bgi9KYnQOxa5RR2EKdadujdg= +github.com/UpCloudLtd/progress v1.0.3/go.mod h1:iGxOnb9HvHW0yrLGUjHr0lxHhn7TehgWwh7a8NqK6iQ= +github.com/bradleyjkemp/cupaloy/v2 v2.8.0 h1:any4BmKE+jGIaMpnU8YgH/I2LPiLBufr6oMMlVBbn9M= +github.com/bradleyjkemp/cupaloy/v2 v2.8.0/go.mod h1:bm7JXdkRd4BHJk9HpwqAI8BoAY1lps46Enkdqw6aRX0= +github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= +github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= +github.com/jedib0t/go-pretty/v6 v6.6.5 h1:9PgMJOVBedpgYLI56jQRJYqngxYAAzfEUua+3NgSqAo= +github.com/jedib0t/go-pretty/v6 v6.6.5/go.mod h1:Uq/HrbhuFty5WSVNfjpQQe47x16RwVGXIveNGEyGtHs= +github.com/mattn/go-runewidth v0.0.16 h1:E5ScNMtiwvlvB5paMFdw9p4kSQzbXFikJ5SQO6TULQc= +github.com/mattn/go-runewidth v0.0.16/go.mod h1:Jdepj2loyihRzMpdS35Xk/zdY8IAYHsh153qUoGf23w= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc= +github.com/rivo/uniseg v0.4.7 h1:WUdvkW8uEhrYfLC4ZzdpI2ztxP1I582+49Oc5Mq64VQ= +github.com/rivo/uniseg v0.4.7/go.mod h1:FN3SvrM+Zdj16jyLfmOkMNblXMcoc8DfTHruCPUcx88= +github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= +github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM= +github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y= +github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA= +github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= +github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk= +github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo= +golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA= +golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA= +golang.org/x/term v0.27.0 h1:WP60Sv1nlK1T6SupCHbXzSaN0b9wUmsPoRS9b61A23Q= +golang.org/x/term v0.27.0/go.mod h1:iMsnZpn0cago0GOrHO2+Y7u7JPn5AylBrcoWkElMTSM= +golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo= +golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/.ci/tools/tools.go b/.ci/tools/tools.go new file mode 100644 index 000000000..ab3a64aad --- /dev/null +++ b/.ci/tools/tools.go @@ -0,0 +1,8 @@ +//go:build tools +// +build tools + +package main + +import ( + _ "github.com/UpCloudLtd/mdtest" +) diff --git a/Makefile b/Makefile index a26d6765c..0125f8710 100644 --- a/Makefile +++ b/Makefile @@ -26,6 +26,8 @@ BIN_FREEBSD = $(CLI_BIN)-$(VERSION)-freebsd-amd64 V = 0 Q = $(if $(filter 1,$V),,@) +TOOLS_DIR:=$(CURDIR)/.ci/bin + export GO111MODULE=on .PHONY: build @@ -45,7 +47,7 @@ clean-md-docs: md-docs: clean-md-docs ## Generate documentation (markdown) $(GO) run ./.ci/docs/ cp CHANGELOG.md docs/changelog.md - cp -r examples/ docs/examples/ + mkdir -p docs/examples/ .PHONY: clean-docs clean-docs: @@ -55,11 +57,12 @@ clean-docs: .PHONY: install-docs-tools install-docs-tools: $(PIP) install -r requirements.txt + cd .ci/tools && GOBIN=$(TOOLS_DIR) go install github.com/UpCloudLtd/mdtest .PHONY: docs docs: clean-docs md-docs install-docs-tools ## Generate documentation (mkdocs site) + $(TOOLS_DIR)/mdtest normalise examples/ -o docs/examples/ -t filename=title --quote-values always $(PYTHON) .ci/docs/generate_dynamic_nav.py - $(PYTHON) .ci/docs/prepare_info_texts_for_mkdocs.py echo "latest_release: $(LATEST_RELEASE)" > vars.yaml mkdocs build