Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Version 8 man pages preparations #176

Merged
merged 4 commits into from
Sep 24, 2024
Merged

Version 8 man pages preparations #176

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
36bc674
Move valkey.conf man page to section 5 (was 4)
zuiderkwast Sep 23, 2024
52e3dc3
Add date and version variables in Makefile
zuiderkwast Sep 23, 2024
d2a1f06
Generate gzipped man pages
zuiderkwast Sep 23, 2024
5a91da8
Use date and version from git if we're in a git repo
zuiderkwast Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
96 changes: 62 additions & 34 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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/*)
Expand Down Expand Up @@ -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*

# -------

Expand Down
5 changes: 4 additions & 1 deletion utils/build-command-index.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand All @@ -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")
Expand Down
2 changes: 1 addition & 1 deletion utils/links-to-man.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 == '':
Expand Down
15 changes: 10 additions & 5 deletions utils/preprocess-markdown.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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('---')
Expand Down Expand Up @@ -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"

Expand All @@ -317,6 +321,7 @@ def main():
data = {
"name": pagename,
"date": yyyymmdd,
"version": args.version,
"suffix": args.suffix,
"pagetype": args.page_type
}
Expand Down