From 1fab7e4b7b78e718f18f11a348fb17084b850290 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Tue, 7 Jul 2026 17:55:31 +0200 Subject: [PATCH 1/2] Add godoc generation. --- README.md | 22 ++++++++++ doc.go | 45 +++++++++++++++++++ scripts/godoc | 105 ++++++++++++++++++++++++++++++++++++++++++++ scripts/godoc-serve | 17 +++++++ 4 files changed, 189 insertions(+) create mode 100644 doc.go create mode 100755 scripts/godoc create mode 100755 scripts/godoc-serve diff --git a/README.md b/README.md index 7f070e0..7cacf03 100644 --- a/README.md +++ b/README.md @@ -77,5 +77,27 @@ Run the executable showcase: go test -tags showcase ./showcase ``` +## Documentation + +The main user guide is the [showcase](showcase/README.md). +Go package docs are useful for maintainers who need to browse package comments +and exported APIs. + +Generate static API docs: + +```bash +./scripts/godoc +``` + +The script writes `build/godoc/` and prints the generated main index file link. + +Launch the GoDoc server: + +```bash +./scripts/godoc-serve +``` + +Open the package link printed by the script. + [embed-code-jekyll]: https://github.com/SpineEventEngine/embed-code [releases]: https://github.com/SpineEventEngine/embed-code-go/releases diff --git a/doc.go b/doc.go new file mode 100644 index 0000000..6046b5b --- /dev/null +++ b/doc.go @@ -0,0 +1,45 @@ +/* + * Copyright 2026, TeamDev. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Redistribution and use in source and/or binary forms, with or without + * modification, must retain the above copyright notice and the following + * disclaimer. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + */ + +// Command embed-code-go keeps documentation snippets synchronized with source files. +// +// Embed Code scans Markdown and HTML documents for instructions, +// resolves the requested source content, and updates or checks the following +// code fence. +// +// The command supports two modes: +// - check mode verifies that embedded snippets match their source files; +// - embed mode rewrites documentation files with current source content. +// +// Source content can be selected from whole files, named fragments, source-line +// ranges, or single matching lines. The command can also filter source comments +// before rendering examples. +// +// The command-line interface accepts direct code and documentation roots or a +// YAML configuration file. The README and showcase contain the user guide and +// runnable examples; GoDoc is primarily useful for maintainers browsing package +// structure and API comments. +package main diff --git a/scripts/godoc b/scripts/godoc new file mode 100755 index 0000000..beecc22 --- /dev/null +++ b/scripts/godoc @@ -0,0 +1,105 @@ +#!/usr/bin/env bash + +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "${repo_root}" + +: "${GODOC_MODULE:=embed-code/embed-code-go}" +: "${GODOC_EXCLUDE_REGEX:=/my-test/}" +: "${GODOC_GOCACHE:=/tmp/embed-code-go-godoc-cache}" +: "${GODOC_OUT:=build/godoc}" +: "${GODOC:=go run golang.org/x/tools/cmd/godoc@v0.24.0}" + +relative_prefix() { + local rel_path="$1" + local prefix="." + + if [[ -n "${rel_path}" ]]; then + IFS="/" read -r -a parts <<< "${rel_path}" + prefix=".." + for ((i = 1; i < ${#parts[@]}; i++)); do + prefix="${prefix}/.." + done + fi + + printf "%s" "${prefix}" +} + +rewrite_links() { + local html_file="$1" + local current_rel="$2" + local prefix + + prefix="$(relative_prefix "${current_rel}")" + sed -i.bak "s#=\"/lib/godoc/#=\"${prefix}/lib/godoc/#g" "${html_file}" + sed -i.bak "s#href=\"/pkg/\"#href=\"${prefix}/index.html\"#g" "${html_file}" + sed -i.bak "s#href=\"/src/${GODOC_MODULE}/#href=\"${prefix}/../../#g" "${html_file}" + + for target_rel in "${package_rels[@]}"; do + local search + local replacement + + if [[ -z "${target_rel}" ]]; then + search="href=\"/pkg/${GODOC_MODULE}/" + replacement="href=\"${prefix}/index.html" + else + search="href=\"/pkg/${GODOC_MODULE}/${target_rel}/" + if [[ "${prefix}" == "." ]]; then + replacement="href=\"${target_rel}/index.html" + sed -i.bak "s#href=\"${target_rel}/\"#href=\"${target_rel}/index.html\"#g" "${html_file}" + else + replacement="href=\"${prefix}/${target_rel}/index.html" + if [[ "${target_rel}" == "${current_rel}/"* ]]; then + child_rel="${target_rel#${current_rel}/}" + if [[ "${child_rel}" != */* ]]; then + sed -i.bak "s#href=\"${child_rel}/\"#href=\"${child_rel}/index.html\"#g" "${html_file}" + fi + fi + fi + fi + sed -i.bak "s#${search}#${replacement}#g" "${html_file}" + done + + LC_ALL=C perl -0pi.bak -e 's~href="/pkg/([^"#]+)(#[^"]*)?"~href="https://pkg.go.dev/$1$2"~g' "${html_file}" + rm -f "${html_file}.bak" +} + +rm -rf "${GODOC_OUT}" +mkdir -p "${GODOC_OUT}/lib/godoc" + +read -r -a godoc_command <<< "${GODOC}" +package_paths=() +package_rels=() + +while IFS= read -r package_path; do + package_paths+=("${package_path}") + package_rel="${package_path#${GODOC_MODULE}}" + package_rels+=("${package_rel#/}") +done < <(GOCACHE="${GODOC_GOCACHE}" go list ./... | grep -Ev "${GODOC_EXCLUDE_REGEX}") + +for asset in style.css jquery.js godocs.js; do + GOCACHE="${GODOC_GOCACHE}" "${godoc_command[@]}" \ + -url="/lib/godoc/${asset}" > "${GODOC_OUT}/lib/godoc/${asset}" +done + +for i in "${!package_paths[@]}"; do + package_path="${package_paths[$i]}" + package_rel="${package_rels[$i]}" + + if [[ -z "${package_rel}" ]]; then + html_file="${GODOC_OUT}/index.html" + else + html_file="${GODOC_OUT}/${package_rel}/index.html" + fi + + mkdir -p "$(dirname "${html_file}")" + GOCACHE="${GODOC_GOCACHE}" "${godoc_command[@]}" \ + -links=false \ + -url="/pkg/${package_path}/" > "${html_file}" + rewrite_links "${html_file}" "${package_rel}" +done + +index_file="${GODOC_OUT}/index.html" +index_path="$(cd "$(dirname "${index_file}")" && pwd)/$(basename "${index_file}")" +printf "GoDoc API documentation generated successfully.\nMain index: file://%s\n" "${index_path}" diff --git a/scripts/godoc-serve b/scripts/godoc-serve new file mode 100755 index 0000000..6968536 --- /dev/null +++ b/scripts/godoc-serve @@ -0,0 +1,17 @@ +#!/usr/bin/env bash + +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "${repo_root}" + +: "${GODOC_MODULE:=embed-code/embed-code-go}" +: "${GODOC_GOCACHE:=/tmp/embed-code-go-godoc-cache}" +: "${GODOC_HOST:=localhost}" +: "${GODOC_PORT:=6061}" +: "${GODOC:=go run golang.org/x/tools/cmd/godoc@v0.24.0}" + +read -r -a godoc_command <<< "${GODOC}" + +printf "Open: http://%s:%s/pkg/%s/\n" "${GODOC_HOST}" "${GODOC_PORT}" "${GODOC_MODULE}" +GOCACHE="${GODOC_GOCACHE}" exec "${godoc_command[@]}" -http="${GODOC_HOST}:${GODOC_PORT}" From 3fa5ac3f93f2a33e4b704b351e056d86ecfdf922 Mon Sep 17 00:00:00 2001 From: Vladyslav Kuksiuk Date: Wed, 8 Jul 2026 11:58:11 +0200 Subject: [PATCH 2/2] Fix folder permissions issue. --- scripts/godoc | 6 +++++- scripts/godoc-serve | 8 ++++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/scripts/godoc b/scripts/godoc index beecc22..2791a08 100755 --- a/scripts/godoc +++ b/scripts/godoc @@ -7,10 +7,14 @@ cd "${repo_root}" : "${GODOC_MODULE:=embed-code/embed-code-go}" : "${GODOC_EXCLUDE_REGEX:=/my-test/}" -: "${GODOC_GOCACHE:=/tmp/embed-code-go-godoc-cache}" : "${GODOC_OUT:=build/godoc}" : "${GODOC:=go run golang.org/x/tools/cmd/godoc@v0.24.0}" +if [[ -z "${GODOC_GOCACHE:-}" ]]; then + GODOC_GOCACHE="$(mktemp -d "${TMPDIR:-/tmp}/embed-code-go-godoc-cache.XXXXXXXXXX")" + trap 'rm -rf "${GODOC_GOCACHE}"' EXIT +fi + relative_prefix() { local rel_path="$1" local prefix="." diff --git a/scripts/godoc-serve b/scripts/godoc-serve index 6968536..914f431 100755 --- a/scripts/godoc-serve +++ b/scripts/godoc-serve @@ -6,12 +6,16 @@ repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" cd "${repo_root}" : "${GODOC_MODULE:=embed-code/embed-code-go}" -: "${GODOC_GOCACHE:=/tmp/embed-code-go-godoc-cache}" : "${GODOC_HOST:=localhost}" : "${GODOC_PORT:=6061}" : "${GODOC:=go run golang.org/x/tools/cmd/godoc@v0.24.0}" +if [[ -z "${GODOC_GOCACHE:-}" ]]; then + GODOC_GOCACHE="$(mktemp -d "${TMPDIR:-/tmp}/embed-code-go-godoc-cache.XXXXXXXXXX")" + trap 'rm -rf "${GODOC_GOCACHE}"' EXIT +fi + read -r -a godoc_command <<< "${GODOC}" printf "Open: http://%s:%s/pkg/%s/\n" "${GODOC_HOST}" "${GODOC_PORT}" "${GODOC_MODULE}" -GOCACHE="${GODOC_GOCACHE}" exec "${godoc_command[@]}" -http="${GODOC_HOST}:${GODOC_PORT}" +GOCACHE="${GODOC_GOCACHE}" "${godoc_command[@]}" -http="${GODOC_HOST}:${GODOC_PORT}"