Merge pull request #76 from ByteInternet/build_manpage

vdloo · web-flow · commit 99a456552607 · 2023-01-22T13:29:52.000+01:00
Add bin/build_manpage for building docs as man page
diff --git a/README.md b/README.md
@@ -66,3 +66,48 @@ Then deploy to your local Hypernode Docker:
 docker run --rm -it --env SSH_PRIVATE_KEY="$(cat ~/.ssh/yourdeploykey | base64)" -v ${PWD}:/build quay.io/hypernode/deploy:latest hypernode-deploy build -vvv  # First build the artifact
 docker run --rm -it --env SSH_PRIVATE_KEY="$(cat ~/.ssh/yourdeploykey | base64)" -v ${PWD}:/build quay.io/hypernode/deploy:latest hypernode-deploy deploy docker -vvv  # Then perform the deploy
 ```
+
+## Building the manpage deb
+
+The docs are also packaged as a debian package named `hndocsnext` so that on a Hypernode you can run `man hypernode` (or `hypernode-manual`) and page through a `manpage` version of the Hypernode docs. To build that debian package on a Debian machine you can run these commands:
+```
+# First create the cow environment
+export ARCH=amd64
+export DIST=buster
+apt-get install debhelper cowbuilder git-buildpackage
+cowbuilder --create --distribution buster --architecture amd64 --basepath /var/cache/pbuilder/base-$DIST-amd64.cow --mirror http://ftp.debian.org/debian/ --components=main
+
+# We need to make sure our build process can use networking in order to pip install the requirements
+echo "USENETWORK=yes" > ~/.pbuilderrc
+
+# Then clone the repository and build the .deb
+git clone https://github.com/ByteInternet/hypernode-docs-next
+cd hypernode-docs-next
+gbp buildpackage --git-pbuilder --git-dist=$DIST --git-arch=$ARCH --git-ignore-branch -us -uc -sa --git-ignore-new
+```
+
+Then after building the Deb you could install it with dpkg. For example:
+```
+dpkg -i ../hndocsnext_20230121.173551_all.deb
+```
+
+And test it out with:
+```
+man hypernode
+```
+
+To inspect the contents of the deb archive you can run:
+```
+# dpkg -L hndocsnext
+/.
+/usr
+/usr/local
+/usr/local/man
+/usr/local/man/man3
+/usr/local/man/man3/hypernode.3
+/usr/share
+/usr/share/doc
+/usr/share/doc/hndocsnext
+/usr/share/doc/hndocsnext/README.md
+/usr/share/doc/hndocsnext/changelog.gz
+```
diff --git a/bin/build_manpage b/bin/build_manpage
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+set -e
+
+pushd docs
+make man
+echo "manpage located at $(realpath _build/man/docs.1)"
+popd
diff --git a/debian/changelog b/debian/changelog
@@ -0,0 +1,6 @@
+hndocsnext (20230121.173551) UNRELEASED; urgency=medium
+
+  [ Rick van de Loo ]
+  * Initial packaging
+
+ -- Rick van de Loo <vdloo@desktop>  Sat, 21 Jan 2023 17:35:51 +0200
diff --git a/debian/compat b/debian/compat
@@ -0,0 +1 @@
+9
diff --git a/debian/control b/debian/control
@@ -0,0 +1,13 @@
+Source: hndocsnext
+Priority: optional
+Maintainer: Hypernode Tech Team <support@hypernode.com>
+Build-Depends: debhelper (>= 9), python3, python3-venv, python3-dev
+Standards-Version: 3.9.4
+Homepage: https://github.com/ByteInternet/hypernode-docs-next
+Vcs-Git: git@github.com:ByteInternet/hypernode-docs-next.git
+
+Package: hndocsnext
+Section: doc
+Architecture: all
+Depends: ${misc:Depends}
+Description: Hypernode docs in manpage form. Run 'man hypernode'.
diff --git a/debian/docs b/debian/docs
@@ -0,0 +1 @@
+README.md
diff --git a/debian/hndocsnext.install b/debian/hndocsnext.install
@@ -0,0 +1,3 @@
+# https://www.debian.org/doc/manuals/maint-guide/dother.en.html#install
+
+docs/_build/man/hypernode.3 /usr/local/man/man3/
diff --git a/debian/hndocsnext.postinst b/debian/hndocsnext.postinst
@@ -0,0 +1,3 @@
+#!/bin/sh
+set -e
+mandb
diff --git a/debian/rules b/debian/rules
@@ -0,0 +1,17 @@
+#!/usr/bin/make -f
+# -*- makefile -*-
+
+# Uncomment this to turn on verbose mode.
+#export DH_VERBOSE=1
+.PHONY: build
+
+build:
+	python3 -m venv venv
+	venv/bin/pip install -r requirements/development.txt
+	bash -c 'source venv/bin/activate; bin/build_manpage'
+	mv docs/_build/man/docs.1 docs/_build/man/hypernode.3
+
+override_dh_usrlocal:
+
+%:
+	dh $@
diff --git a/debian/source/format b/debian/source/format
@@ -0,0 +1 @@
+3.0 (native)
diff --git a/mark-release.sh b/mark-release.sh
@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+
+read -r -d '' USAGE << EOUSAGE
+Mark a release for project, ensure commits in master are in debian changelog.
+If there are changes to release, update version and debian changelog,
+also can tag and push the release.
+If all commits are in changelog, won't change anything.
+The last line of output indicates if a release is marked or not.
+usage: $0 [options]
+options:
+    -a          automated mode (commit, tag, push)
+    -c          commit the changes for marking the release
+    -h          show this help and exit
+    -p          git push HEAD and tags
+    -t          tag the commit
+    -v          verbose output
+environment:
+    AUTHOR      commit author (name <email>) format
+    DEBFULLNAME changelog writer name
+    DEBEMAIL    changelog writer email
+    MESSAGE     commit message
+EOUSAGE
+
+# ==== opts ====
+COMMIT=false
+PUSH=false
+TAG=false
+VERBOSE=false
+
+while getopts 'achptv' flag; do
+case "$flag" in
+    a)
+        COMMIT=true
+        TAG=true
+        PUSH=true
+        ;;
+    c)
+        COMMIT=true
+        ;;
+    h)
+        echo "$USAGE"
+        exit
+        ;;
+    p)
+        PUSH=true
+        ;;
+    t)
+        TAG=true
+        ;;
+    v)
+        VERBOSE=true
+        ;;
+esac
+done
+
+
+set -o errexit
+
+ROOT_DIR=$(realpath $(dirname $0))
+CHANGELOG="$ROOT_DIR/debian/changelog"
+VERSION=$(date "+%Y%m%d.%H%M%S")
+LOG_USER="${SUDO_USER:-$USER}"
+
+# === options from env ====
+
+# committer info
+AUTHOR="${AUTHOR:-}"
+MESSAGE="${MESSAGE}"
+if [[ -z "$MESSAGE" ]]; then
+    MESSAGE="[automated] Marking Release $VERSION"
+fi
+
+# changelog writer info
+export DEBFULLNAME="${DEBFULLNAME:-Hypernode team}"
+export DEBEMAIL="${DEBMAIL:-hypernode@byte.nl}"
+
+
+log() {
+    logger --tag 'hypernode-docs-next-mark-release' "[$$ @$LOG_USER] $1"
+    if $VERBOSE; then
+        echo "$1"
+    fi
+}
+
+# deb_changelog_updated: returns 0 if there are changes to be released or 1 otherwise
+deb_changelog_updated() {
+    log "checking if debian changelog needs update"
+    # use gbp dch itself to see if there are any changes detected.
+    # this way the logic of detecting changes is more consistent with
+    # the rest of the system.
+    gbp dch --debian-tag="%(version)s" --debian-branch=master
+    # find changelog diff to see if there new commits in changelog.
+    # commits are usually added like this to the changelog:
+    #  [ author ]
+    #  * commit message
+    # first look for commit messages, if nothing found, then see if there is an empty author section,
+    # as a fallback.
+    local changed=$(git diff --text --ignore-all-space --unified=0 --no-color $CHANGELOG | grep --line-regexp --perl-regexp '\+\s{2,}\* .+')
+    if [[ -z "$changed" ]]; then
+        changed=$(git diff --text --ignore-all-space --unified=0 --no-color $CHANGELOG | grep --line-regexp --perl-regexp '\+\\s{2,}\[.+\].*')
+    fi
+    log "reverting possible changes in debian changelog during update detection"
+    git checkout -- $CHANGELOG
+    if [[ -n "$changed" ]]; then
+        return 0
+    fi
+    return 1
+}
+
+mark_release() {
+    log "marking release $VERSION ..."
+
+    log "generating debian changelog"
+    gbp dch --debian-tag="%(version)s" --new-version=$VERSION --debian-branch=master
+    git add $CHANGELOG
+}
+
+commit() {
+    log "comitting the release changes"
+    if [[ -z "$AUTHOR" ]]; then
+        git commit --no-edit --message="$MESSAGE"
+    else
+        git commit --no-edit --message="$MESSAGE" --author "$AUTHOR"
+    fi
+}
+
+
+if ! deb_changelog_updated; then
+    log "detected no change, skipping marking release!"
+    echo 'no change'
+    exit
+fi
+
+mark_release
+
+if $COMMIT; then
+    commit
+    if $TAG; then
+        log "creating git tag '$VERSION' ..."
+        git tag $VERSION
+    fi
+
+    if $PUSH; then
+        log "pushing changes to origin ..."
+        git push origin HEAD
+        if $TAG; then
+            git push origin $VERSION
+        fi
+    fi
+else
+    log "not committing, skipping tagging and pushing!"
+fi
+
+echo "marked release $VERSION"

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# https://www.debian.org/doc/manuals/maint-guide/dother.en.html#install`
	`2`	`+`
	`3`	`+docs/_build/man/hypernode.3 /usr/local/man/man3/`