From 06bcac66109470fdec559c3f8a6c8773e12ab8dc Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 17 Jan 2025 12:45:49 +0100 Subject: [PATCH 1/5] doc: order pages in octezdoc.txt --- docs/Makefile | 6 +++--- docs/scripts/octezdoc-excludes.txt | 14 ++++++++++++++ docs/scripts/octezdoc.sh | 15 +++++++++++++++ 3 files changed, 32 insertions(+), 3 deletions(-) create mode 100644 docs/scripts/octezdoc-excludes.txt create mode 100755 docs/scripts/octezdoc.sh diff --git a/docs/Makefile b/docs/Makefile index 79e02f684f5e..374679ad9e64 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -51,12 +51,12 @@ html: octez-gen docexes-gen ${MAKE} sphinx # Make all the doc in a single text file -octezdoc.txt: octez-gen docexes-gen +$(BUILDDIR)/octezdoc.txt: $(BUILDDIR)/index.html rm -fr $(BUILDDIRTXT) (echo ':orphan:'; echo ''; cat ../CHANGES.rst) > CHANGES-dev.rst touch CHANGES-dev.rst @$(SPHINXBUILD) --builder text "$(SOURCEDIR)" $(BUILDDIRTXT) $(SPHINXOPTS) - find $(BUILDDIRTXT) -name "*.txt" | xargs cat >$@ + $(SCRIPTSDIR)/octezdoc.sh >$@ # Build the manuals for a given protocol %/octez-client.html: @@ -312,7 +312,7 @@ fmt: black .PHONY: clean clean: - @-rm -Rf "$(BUILDDIR)" linkcheck odoc.log + @-rm -Rf "$(BUILDDIR)" "$(BUILDDIRTXT)" linkcheck odoc.log @-rm -f $(ERRDOCEXE) $(RPCDOCEXE) $(P2PDOCEXE) @-rm -Rf api/errors.rst developer/metrics.csv user/node-config.json alpha/rpc.rst shell/rpc.rst shell/p2p_api.rst user/default-acl.json CHANGES-dev.rst developer/rollup_metrics.csv octezdoc.txt @-rm -Rf api/octez-*.html api/octez-*.txt paris/octez-*.html alpha/octez-*.html quebec/octez-*.html diff --git a/docs/scripts/octezdoc-excludes.txt b/docs/scripts/octezdoc-excludes.txt new file mode 100644 index 000000000000..cee5e6a3123f --- /dev/null +++ b/docs/scripts/octezdoc-excludes.txt @@ -0,0 +1,14 @@ +^active/cli-commands.txt +^active/rpc.txt +^api/api-inline.txt +^api/errors.txt +^developer/openmetrics.txt +^developer/rollup_metrics.txt +^shell/p2p_api.txt +^.*/cli-commands.txt +^shell/rpc.txt +^quebec/ +^alpha/ +^releases/ +^protocols/ +^developer/merkle-proof-formats/ diff --git a/docs/scripts/octezdoc.sh b/docs/scripts/octezdoc.sh new file mode 100755 index 000000000000..a5ae92f4a728 --- /dev/null +++ b/docs/scripts/octezdoc.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +# Generate a single-file text version of the documentation usable by bots + +MYDIR="$(dirname "$0")" +BUILDDIR="$MYDIR"/../_build + +grep 'toctree-l\d' $BUILDDIR/index.html | \ + sed 's|^.*href="||; s|.html">.*$|.txt|'|\ + grep -v -f $MYDIR/octezdoc-excludes.txt | \ + while read f + do + cat _build_txt/$f + # insert blank line + echo "" + done -- GitLab From e62714cc0d18be2dffc9178516579ae52358e67e Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 17 Jan 2025 12:46:22 +0100 Subject: [PATCH 2/5] doc: publish octezdoc.txt --- scripts/ci/doc_publish.sh | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/ci/doc_publish.sh b/scripts/ci/doc_publish.sh index 8d1c2e335161..ef0f17950fb5 100755 --- a/scripts/ci/doc_publish.sh +++ b/scripts/ci/doc_publish.sh @@ -5,6 +5,8 @@ set -e cd "${CI_PROJECT_DIR}" || exit 1 if [ "${CI_COMMIT_REF_NAME}" == "master" ]; then + make -C docs _build/octezdoc.txt + git clone --depth 5 git@gitlab.com:"${CI_PROJECT_NAMESPACE}"/"${CI_PROJECT_NAMESPACE}".gitlab.io gitlab.io rsync --recursive --links --perms --delete --exclude=.doctrees --exclude={{main,alpha,zero}net,master}/index.html docs/_build/ gitlab.io/public/ cd gitlab.io || exit 2 -- GitLab From 12a1e7b762763e6e80e93331e2a96c5da87f2adc Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 17 Jan 2025 14:32:13 +0100 Subject: [PATCH 3/5] doc: fix format & syntax of octezdoc.sh --- docs/scripts/octezdoc.sh | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/scripts/octezdoc.sh b/docs/scripts/octezdoc.sh index a5ae92f4a728..d08f5b752d78 100755 --- a/docs/scripts/octezdoc.sh +++ b/docs/scripts/octezdoc.sh @@ -4,12 +4,11 @@ MYDIR="$(dirname "$0")" BUILDDIR="$MYDIR"/../_build -grep 'toctree-l\d' $BUILDDIR/index.html | \ - sed 's|^.*href="||; s|.html">.*$|.txt|'|\ - grep -v -f $MYDIR/octezdoc-excludes.txt | \ - while read f - do - cat _build_txt/$f +grep 'toctree-l\d' "$BUILDDIR"/index.html | + sed 's|^.*href="||; s|.html">.*$|.txt|' | + grep -v -f "$MYDIR"/octezdoc-excludes.txt | + while read -r f; do + cat _build_txt/"$f" # insert blank line echo "" done -- GitLab From 88c692c98689d18d9d99dd303ec745af8484c8b8 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 21 Jan 2025 15:40:49 +0100 Subject: [PATCH 4/5] doc: update for quebec --- docs/scripts/octezdoc-excludes.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/scripts/octezdoc-excludes.txt b/docs/scripts/octezdoc-excludes.txt index cee5e6a3123f..d872fbe98ae4 100644 --- a/docs/scripts/octezdoc-excludes.txt +++ b/docs/scripts/octezdoc-excludes.txt @@ -7,7 +7,6 @@ ^shell/p2p_api.txt ^.*/cli-commands.txt ^shell/rpc.txt -^quebec/ ^alpha/ ^releases/ ^protocols/ -- GitLab From 987a6fe5d6c4d49240673e5a62540050f63ac9ff Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 22 Jan 2025 16:33:59 +0100 Subject: [PATCH 5/5] doc: add comments to octezdoc.sh --- docs/scripts/octezdoc.sh | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/scripts/octezdoc.sh b/docs/scripts/octezdoc.sh index d08f5b752d78..ed3fcbfcfb47 100755 --- a/docs/scripts/octezdoc.sh +++ b/docs/scripts/octezdoc.sh @@ -4,11 +4,13 @@ MYDIR="$(dirname "$0")" BUILDDIR="$MYDIR"/../_build +# Extract order of pages from the HTML root index, +# then exclude blacklisted pages grep 'toctree-l\d' "$BUILDDIR"/index.html | sed 's|^.*href="||; s|.html">.*$|.txt|' | grep -v -f "$MYDIR"/octezdoc-excludes.txt | while read -r f; do cat _build_txt/"$f" - # insert blank line + # insert blank line at the end of each file echo "" done -- GitLab