Version 8 man pages preparations (#176)

Move valkey.conf man page to section 5 (was 4) Add DATE and VERSION variables in Makefile. These are used in the man page footers. If running in a git repo, the date and version is taken from the git repo and if an exact git tag is checked out, there's a check added that checks that the declared version matches the git tag. This is to help finding mistake in the release process. (Run make after git tag, before pushing the new tag.) Generate and install gzipped man pages. --------- Signed-off-by: Viktor Söderqvist <[email protected]>
valkey-io · Sep 24, 2024 · fa74e02 · fa74e02
1 parent 30b65cd
commit fa74e02
Show file tree

Hide file tree

Showing 4 changed files with 77 additions and 41 deletions.
diff --git a/Makefile b/Makefile
@@ -2,6 +2,10 @@
 # All rights reserved.
 # SPDX-License-Identifier: BSD-3-Clause
 
+# Version info
+VERSION ?= 8.0.0
+DATE ?= 2024-09-23
+
 # Path to the code repo.
 VALKEY_ROOT ?= ../valkey
 
@@ -30,6 +34,22 @@ ifeq ("$(shell which pandoc)","")
     $(error Please install pandoc)
 endif
 
+# ---- If we're in a git repo, override date and version ----
+
+ifneq ($(wildcard .git),)
+    DATE=$(shell git log -1 --format=%cs)
+    described=$(shell git describe --tags --always)
+    # If git returned a clean version on the form X.Y.Z, then check that it
+    # matches the declared VERSION. This is just when tagging.
+    ifneq ($(shell echo $(described) | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$$'),)
+    ifneq ($(described),$(VERSION))
+        $(error Declared VERSION $(VERSION) mismatches git tag $(described))
+    endif
+    endif
+    VERSION=$(described)
+    $(warning $(VERSION) $(DATE))
+endif
+
 # ---- Source files ----
 
 topics   = $(wildcard topics/*)
@@ -125,64 +145,72 @@ configs = topics/valkey.conf.md
 
 man1_src = $(filter $(programs),$(topics_md))
 man3_src = $(commands)
-man4_src = $(filter $(configs),$(topics_md))
+man5_src = $(filter $(configs),$(topics_md))
 man7_src = $(filter-out $(programs) $(configs) topics/index.md,$(topics_md))
 
 # Target man pages
-man1     = $(man1_src:topics/%.md=$(MAN_DIR)/man1/valkey-%.1)
-man3     = $(man3_src:commands/%.md=$(MAN_DIR)/man3/%.3valkey)
-man4     = $(man4_src:topics/%.md=$(MAN_DIR)/man4/%.4)
-man7     = $(man7_src:topics/%.md=$(MAN_DIR)/man7/valkey-%.7) $(MAN_DIR)/man7/valkey-commands.7 $(MAN_DIR)/man7/valkey.7
+man1     = $(man1_src:topics/%.md=$(MAN_DIR)/man1/valkey-%.1.gz)
+man3     = $(man3_src:commands/%.md=$(MAN_DIR)/man3/%.3valkey.gz)
+man5     = $(man5_src:topics/%.md=$(MAN_DIR)/man5/%.5.gz)
+man7     = $(man7_src:topics/%.md=$(MAN_DIR)/man7/valkey-%.7.gz) $(MAN_DIR)/man7/valkey-commands.7.gz $(MAN_DIR)/man7/valkey.7.gz
 
-man_targets = $(man1) $(man3) $(man4) $(man7)
+man_targets = $(man1) $(man3) $(man5) $(man7)
 
 $(man1): | $(MAN_DIR)/man1
 $(man3): | $(MAN_DIR)/man3
-$(man4): | $(MAN_DIR)/man4
+$(man5): | $(MAN_DIR)/man5
 $(man7): | $(MAN_DIR)/man7
-$(MAN_DIR)/man1 $(MAN_DIR)/man3 $(MAN_DIR)/man4 $(MAN_DIR)/man7:
+$(MAN_DIR)/man1 $(MAN_DIR)/man3 $(MAN_DIR)/man5 $(MAN_DIR)/man7:
 	mkdir -p $@
 
 man_scripts = utils/preprocess-markdown.py utils/command_syntax.py utils/links-to-man.py
+to_man = pandoc -s --to man - | gzip -
 
-$(MAN_DIR)/man1/valkey-%.1: topics/%.md $(man_scripts)
-	utils/preprocess-markdown.py --man --page-type program $< \
-	 | utils/links-to-man.py - | pandoc -s --to man -o $@ -
-$(MAN_DIR)/man3/%.3valkey: commands/%.md $(VALKEY_ROOT)/src/commands/%.json $(BUILD_DIR)/.commands-per-group.json $(man_scripts)
+$(MAN_DIR)/man1/valkey-%.1.gz: topics/%.md $(man_scripts)
+	utils/preprocess-markdown.py --man --page-type program \
+	 --version $(VERSION) --date $(DATE) \$< \
+	 | utils/links-to-man.py - | $(to_man) > $@
+$(MAN_DIR)/man3/%.3valkey.gz: commands/%.md $(VALKEY_ROOT)/src/commands/%.json $(BUILD_DIR)/.commands-per-group.json $(man_scripts)
 	utils/preprocess-markdown.py --man --page-type command \
+	 --version $(VERSION) --date $(DATE) \
 	 --commands-per-group-json $(BUILD_DIR)/.commands-per-group.json \
 	 --valkey-root $(VALKEY_ROOT) $< \
-	 | utils/links-to-man.py - | pandoc -s --to man -o $@ -
-$(MAN_DIR)/man4/%.4: topics/%.md $(man_scripts)
-	utils/preprocess-markdown.py --man --page-type config $< \
-	 | utils/links-to-man.py - | pandoc -s --to man -o $@ -
-$(MAN_DIR)/man7/valkey-%.7: topics/%.md $(man_scripts)
-	utils/preprocess-markdown.py --man --page-type topic $< \
-	 | utils/links-to-man.py - | pandoc -s --to man -o $@ -
-$(MAN_DIR)/man7/valkey.7: topics/index.md $(man_scripts)
-	utils/preprocess-markdown.py --man --page-type topic $< \
-	 | utils/links-to-man.py - | pandoc -s --to man -o $@ -
-$(MAN_DIR)/man7/valkey-commands.7: $(BUILD_DIR)/.commands-per-group.json groups.json utils/build-command-index.py
+	 | utils/links-to-man.py - | $(to_man) > $@
+$(MAN_DIR)/man5/%.5.gz: topics/%.md $(man_scripts)
+	utils/preprocess-markdown.py --man --page-type config \
+	 --version $(VERSION) --date $(DATE) $< \
+	 | utils/links-to-man.py - | $(to_man) > $@
+$(MAN_DIR)/man7/valkey-%.7.gz: topics/%.md $(man_scripts)
+	utils/preprocess-markdown.py --man --page-type topic \
+	 --version $(VERSION) --date $(DATE) $< \
+	 | utils/links-to-man.py - | $(to_man) > $@
+$(MAN_DIR)/man7/valkey.7.gz: topics/index.md $(man_scripts)
+	utils/preprocess-markdown.py --man --page-type topic \
+	 --version $(VERSION) --date $(DATE) $< \
+	 | utils/links-to-man.py - | $(to_man) > $@
+$(MAN_DIR)/man7/valkey-commands.7.gz: $(BUILD_DIR)/.commands-per-group.json groups.json utils/build-command-index.py
 	utils/build-command-index.py --man \
+	 --version $(VERSION) --date $(DATE) \
 	 --groups-json groups.json \
 	 --commands-per-group-json $(BUILD_DIR)/.commands-per-group.json \
-	 | pandoc -s --to man -o $@ -
+	 | $(to_man) > $@
 
 .PHONY: install-man uninstall-man
-install-man: man | $(INSTALL_MAN_DIR)/man1 $(INSTALL_MAN_DIR)/man3 $(INSTALL_MAN_DIR)/man4 $(INSTALL_MAN_DIR)/man7
-	cp $(MAN_DIR)/man1/valkey*.1 $(INSTALL_MAN_DIR)/man1/
-	cp $(MAN_DIR)/man3/*.3valkey $(INSTALL_MAN_DIR)/man3/
-	cp $(MAN_DIR)/man4/valkey*.4 $(INSTALL_MAN_DIR)/man4/
-	cp $(MAN_DIR)/man7/valkey*.7 $(INSTALL_MAN_DIR)/man7/
+install-man: man | $(INSTALL_MAN_DIR)/man1 $(INSTALL_MAN_DIR)/man3 $(INSTALL_MAN_DIR)/man5 $(INSTALL_MAN_DIR)/man7
+	cp $(MAN_DIR)/man1/valkey*.1.gz $(INSTALL_MAN_DIR)/man1/
+	cp $(MAN_DIR)/man3/*.3valkey.gz $(INSTALL_MAN_DIR)/man3/
+	cp $(MAN_DIR)/man5/valkey*.5.gz $(INSTALL_MAN_DIR)/man5/
+	cp $(MAN_DIR)/man7/valkey*.7.gz $(INSTALL_MAN_DIR)/man7/
 
-$(INSTALL_MAN_DIR)/man1 $(INSTALL_MAN_DIR)/man3 $(INSTALL_MAN_DIR)/man4 $(INSTALL_MAN_DIR)/man7:
+$(INSTALL_MAN_DIR)/man1 $(INSTALL_MAN_DIR)/man3 $(INSTALL_MAN_DIR)/man5 $(INSTALL_MAN_DIR)/man7:
 	mkdir -p $@
 
 uninstall-man:
-	rm $(INSTALL_MAN_DIR)/man1/valkey*.1
-	rm $(INSTALL_MAN_DIR)/man3/*.3valkey
-	rm $(INSTALL_MAN_DIR)/man4/valkey*.4
-	rm $(INSTALL_MAN_DIR)/man7/valkey*.7
+	rm -f $(INSTALL_MAN_DIR)/man1/valkey*.1*
+	rm -f $(INSTALL_MAN_DIR)/man3/*.3valkey*
+	rm -f $(INSTALL_MAN_DIR)/man4/valkey*.4*
+	rm -f $(INSTALL_MAN_DIR)/man5/valkey*.5*
+	rm -f $(INSTALL_MAN_DIR)/man7/valkey*.7*
 
 # -------
 

diff --git a/utils/build-command-index.py b/utils/build-command-index.py
@@ -19,6 +19,8 @@
 parser.add_argument('--suffix', default='.md',
                     help='Suffix to use in internal links instead of .md for non-manpage usage')
 parser.add_argument('--man', action='store_true', help='Generate markdown for man page')
+parser.add_argument('--date', default='', help='Date on the form YYYY-MM-DD')
+parser.add_argument('--version', default='', help='Version on the form X.Y.Z')
 parser.add_argument('--groups-json', help='groups.json')
 parser.add_argument('--commands-per-group-json', help='commands-per-groups.json')
 args = parser.parse_args()
@@ -32,7 +34,8 @@
     print("---")
     print("title: VALKEY-COMMANDS(7)")
     print('header: Valkey Command Manual')
-    print('footer: Valkey Documentation')
+    print('footer: %s' % args.version)
+    print('date: %s' % args.date)
     print('adjusting: left')
     print("---")
     print('# NAME', end="\n\n")

diff --git a/utils/links-to-man.py b/utils/links-to-man.py
@@ -53,7 +53,7 @@ def page_to_man(text, dir, name):
         if name == '' or name == '.':
             return '**valkey**(7)'
         elif name == 'valkey.conf':
-            return '**valkey.conf**(4)'
+            return '**valkey.conf**(5)'
         elif name in ['cli', 'check-aof', 'check-rdb', 'benchmark', 'server', 'sentinel']:
             return '**valkey-%s**(1)' % name
         elif text == '':

diff --git a/utils/preprocess-markdown.py b/utils/preprocess-markdown.py
@@ -20,7 +20,7 @@
     'LIBRARY',                  # Not used (possibly use module API functions)
     'SYNOPSIS',                 # Inserted automatically for commands. Written
                                 # explicitly as "## Usage" for programs.
-    'CONFIGURATION',            # Explicit for valkey.conf(4)
+    'CONFIGURATION',            # Explicit for valkey.conf(5)
     'DESCRIPTION',              # Inserted automatically before any text unless
                                 # another standard heading starts the text
     'OPTIONS',                  # Uses for programs
@@ -59,12 +59,12 @@ def print_top(self):
             print('section: 1')
             print('header: Valkey Manual')
         elif self.pagetype == 'config':
-            print('section: 4')
+            print('section: 5')
             print('header: Valkey Configuration Manual')
         else:
             print('section: 7')
             print('header: Valkey Manual')
-        print('footer: Valkey Documentation')
+        print('footer: %s' % self.version)
         print('date: %s' % self.date)
         print('adjusting: left')
         print('---')
@@ -295,13 +295,17 @@ def main():
                         help='Suffix to use in internal links instead of .md for non-manpage usage')
     parser.add_argument('--base-url', default='https://valkey.io/', help='Used for transforming absolute links to relative ones.')
     parser.add_argument('--man', action='store_true', help='Generate markdown for man page')
+    parser.add_argument('--date', default=None, help='Date on the form YYYY-MM-DD')
+    parser.add_argument('--version', default=None, help='Version on the form X.Y.Z')
     parser.add_argument('filename', help='Markdown file')
     args = parser.parse_args()
 
     # We can use git to find the last change of the file, but only if we're in a git repo.
     # yyyymmdd = os.popen('git log -1 --pretty="format:%cs" ' + args.filename).read()
-    mtime = os.stat(args.filename).st_mtime
-    yyyymmdd = date.fromtimestamp(mtime).isoformat()
+    yyyymmdd = args.date
+    if not args.date:
+        mtime = os.stat(args.filename).st_mtime
+        yyyymmdd = date.fromtimestamp(mtime).isoformat()
 
     name0 = re.sub(r'^.*/([^/]+)\.md$', r'\1', args.filename) # "client-kill"
 
@@ -317,6 +321,7 @@ def main():
     data = {
         "name": pagename,
         "date": yyyymmdd,
+        "version": args.version,
         "suffix": args.suffix,
         "pagetype": args.page_type
     }