diff mbox series

[ndctl] scripts: Add a man page template generator

Message ID 20211215020102.97880-1-vishal.l.verma@intel.com
State New, archived
Headers show
Series [ndctl] scripts: Add a man page template generator | expand

Commit Message

Verma, Vishal L Dec. 15, 2021, 2:01 a.m. UTC
Add a script to generate man page templates for the utils and libraries
under ndctl - including cxl, libcxl, ndctl, and daxctl.

The script can control certain include options depending on the options
supplied, and either dump the templates to stdout, or write the actual
files in their eventual directories, and open up an editor to further
edit them (unless --no-edit is used).

Cc: Dan Williams <dan.j.williams@intel.com>
Signed-off-by: Vishal Verma <vishal.l.verma@intel.com>
---
 scripts/docsurgeon                     | 339 +++++++++++++++++++++++++
 scripts/docsurgeon_parser_generator.m4 |  23 ++
 2 files changed, 362 insertions(+)
 create mode 100755 scripts/docsurgeon
 create mode 100644 scripts/docsurgeon_parser_generator.m4
diff mbox series

Patch

diff --git a/scripts/docsurgeon b/scripts/docsurgeon
new file mode 100755
index 0000000..ca0ad78
--- /dev/null
+++ b/scripts/docsurgeon
@@ -0,0 +1,339 @@ 
+#!/bin/bash -eE
+
+this_script="docsurgeon"
+script_dir="$(cd "$(dirname "$(readlink -e "${BASH_SOURCE[0]}")")" && pwd)"
+env_file="${script_dir}/.env"
+if [ -e "$env_file" ]; then
+	# shellcheck source=.env
+	. "$env_file"
+fi
+
+sources_file="${script_dir}/.sources"
+
+parser_generator="${script_dir}/${this_script}_parser_generator.m4"
+parser_lib="${script_dir}/${this_script}_parser.sh"
+if [ ! -e "$parser_lib" ] || [ "$parser_generator" -nt "$parser_lib" ]; then
+	if command -V argbash > /dev/null; then
+		argbash --strip user-content "$parser_generator" -o "$parser_lib"
+	else
+		echo "error: please install argbash" >&2
+		exit 1
+	fi
+fi
+
+if [[ $1 != "bin" ]]; then
+	# shellcheck source=docsurgeon_parser.sh
+	. "${script_dir}/${this_script}_parser.sh" || { echo "Couldn't find $parser_lib" >&2; exit 1; }
+fi
+
+# some script defaults - override using '.env'
+docbase="Documentation"
+copyright_cli="// SPDX-License-Identifier: GPL-2.0"
+copyright_footer_cli="include::../copyright.txt[]"
+copyright_lib="// SPDX-License-Identifier: LGPL-2.0"
+copyright_footer_lib="include::../../copyright.txt[]"
+
+# List of files we're creating, to be edited/renamed later
+# This starts out blank, and is filled in as we go by gen_*() functions
+declare -a outfiles
+
+cleanup()
+{
+	if [ ${#outfiles[@]} -gt 0 ]; then
+		rm -f "${outfiles[@]}"
+	fi
+	set +x
+}
+
+trap cleanup EXIT
+
+auto_detect_params()
+{
+	fs=""
+	module=""
+	section=""
+
+	# if module and section were explicitly specified, respect them
+	if [[ $_arg_module ]] && [[ $_arg_section ]]; then
+		return
+	fi
+
+	# check if names are self-consistent, and determine 'fs'
+	for name in ${_arg_name[@]}; do
+		if [[ ! $fs ]]; then
+			if [[ $name == *-* ]]; then
+				fs="-"
+			elif [[ $name == *_* ]]; then
+				fs="_"
+			else
+				# can't autodetect section
+				return
+			fi
+		fi
+		if [[ $fs == "-" ]] && [[ $name == *_* ]]; then
+			die "can't auto-detect params with mixed-style names"
+		fi
+		if [[ $fs == "_" ]] && [[ $name == *-* ]]; then
+			die "can't auto-detect params with mixed-style names"
+		fi
+	done
+
+	# try to detect module name
+	for name in ${_arg_name[@]}; do
+		str=${name%%$fs*}
+		if [[ $module ]]; then
+			if [[ $str != $module ]]; then
+				die "Can't autodetect module because of mixed names ($str and $module)"
+			fi
+		else
+			module="$str"
+		fi
+	done
+
+	# try to detect section number
+	case "$fs" in
+	-)
+		section=1
+		;;
+	_)
+		section=3
+		;;
+	*)
+		die "Unknown fs, can't autodetect section number"
+		;;
+	esac
+
+	if [[ $module ]]; then
+		_arg_module="$module"
+	fi
+	if [[ $section ]]; then
+		_arg_section="$section"
+	fi
+}
+
+process_options_logic()
+{
+	if [[ $_arg_debug == "on" ]]; then
+		set -x
+	fi
+
+	auto_detect_params
+}
+
+gen_underline()
+{
+	name="$1"
+	char="$2"
+	num="${#name}"
+
+	printf -v tmpstring "%-${num}s" " "
+	echo "${tmpstring// /$char}"
+}
+
+gen_header()
+{
+	printf "\n%s\n%s\n" "$1" "$(gen_underline "$1" "=")"
+}
+
+gen_section()
+{
+	printf "\n%s\n%s\n" "$1" "$(gen_underline "$1" "-")"
+}
+
+gen_section_name()
+{
+	name="$1"
+
+	gen_section "NAME"
+	cat <<- EOF
+		$name - 
+	EOF
+}
+
+gen_section_synopsis_1()
+{
+	name="$1"
+
+	gen_section "SYNOPSIS"
+	cat <<- EOF
+		[verse]
+		'$_arg_module ${name#*-} [<options>]'
+	EOF
+}
+
+gen_section_synopsis_3()
+{
+	name="$1"
+
+	gen_section "SYNOPSIS"
+	cat <<- EOF
+		[verse]
+		----
+		#include <$_arg_module/lib$_arg_module.h>
+
+		<type> $name();
+		----
+	EOF
+}
+
+gen_section_example_1()
+{
+	name="$1"
+
+	gen_section "EXAMPLE"
+	cat <<- EOF
+		----
+		# $_arg_module ${name#*-}
+		----
+	EOF
+}
+
+gen_section_example_3()
+{
+	name="$1"
+
+	gen_section "EXAMPLE"
+	cat <<- EOF
+		See example usage in test/lib$_arg_module.c
+	EOF
+}
+
+gen_section_options_1()
+{
+	gen_section "OPTIONS"
+cat << EOF
+-o::
+--option::
+	Description
+EOF
+
+	if [[ $_arg_human_option == "on" ]]; then
+		printf "\n%s\n" "include::human-option.txt[]"
+	fi
+	if [[ $_arg_verbose_option == "on" ]]; then
+		printf "\n%s\n" "include::verbose-option.txt[]"
+	fi
+}
+
+gen_section_seealso_1()
+{
+	gen_section "SEE ALSO"
+	cat <<- EOF
+	link$_arg_module:$_arg_module-list[$_arg_section],
+	EOF
+}
+
+gen_section_seealso_3()
+{
+	gen_section "SEE ALSO"
+	cat <<- EOF
+	linklib$_arg_module:${_arg_module}_other_API[$_arg_section],
+	EOF
+}
+
+gen_cli()
+{
+	name="$1"
+	path="$docbase/$_arg_module"
+	if [ ! -d "$path" ]; then
+		die "Not found: $path"
+	fi
+
+	tmp="$(mktemp -p "$path" "$name.txt.XXXX")"
+	outfiles+=("$tmp")
+
+	# Start template generation
+	printf "%s\n" "$copyright_cli" > "$tmp"
+	gen_header "$name" >> "$tmp"
+	gen_section_name "$name" >> "$tmp"
+	gen_section_synopsis_1 "$name" >> "$tmp"
+	gen_section "DESCRIPTION" >> "$tmp"
+	gen_section_example_1 "$name" >> "$tmp"
+	gen_section_options_1 >> "$tmp"
+	printf "\n%s\n" "$copyright_footer_cli" >> "$tmp"
+	gen_section_seealso_1 >> "$tmp"
+}
+
+gen_lib()
+{
+	name="$1"
+	path="$docbase/$_arg_module/lib"
+	if [ ! -d "$path" ]; then
+		die "Not found: $path"
+	fi
+
+	tmp="$(mktemp -p "$path" "$name.txt.XXXX")"
+	outfiles+=("$tmp")
+
+	# Start template generation
+	printf "%s\n" "$copyright_lib" > "$tmp"
+	gen_header "$name($_arg_section)" >> "$tmp"
+	gen_section_name "$name" >> "$tmp"
+	gen_section_synopsis_3 "$name" >> "$tmp"
+	gen_section "DESCRIPTION" >> "$tmp"
+	gen_section "RETURN VALUE" >> "$tmp"
+	gen_section_example_3 "$name" >> "$tmp"
+	printf "\n%s\n" "$copyright_footer_lib" >> "$tmp"
+	gen_section_seealso_3 >> "$tmp"
+}
+
+gen_man()
+{
+	name="$1"
+	case "$_arg_section" in
+	1)
+		gen_cli "$name"
+		;;
+	3)
+		gen_lib "$name"
+		;;
+	*)
+		die "Unknown section: $_arg_section"
+		;;
+	esac
+}
+
+gen_include()
+{
+	echo "in gen_include"
+}
+
+main()
+{
+	process_options_logic
+
+	cmd="$_arg_command"
+	case "$cmd" in
+	gen-man)
+		for name in ${_arg_name[@]}; do
+			gen_man "$name"
+		done
+		;;
+	gen-include)
+		for name in ${_arg_name[@]}; do
+			gen_include
+		done
+		;;
+	*)
+		die "Unknown command: $cmd"
+		;;
+	esac
+
+	if [[ $_arg_dump == "on" ]]; then
+		for file in ${outfiles[@]}; do
+			echo "${file##*/}"
+			cat "$file"
+			rm "$file"
+		done
+	elif [ ${#outfiles[@]} -gt 0 ]; then
+		if [[ $_arg_edit = "on" ]]; then
+			vim -p "${outfiles[@]}"
+		fi
+
+		for file in ${outfiles[@]}; do
+			mv "$file" "${file%.*}"
+		done
+	fi
+}
+
+main "$@"
diff --git a/scripts/docsurgeon_parser_generator.m4 b/scripts/docsurgeon_parser_generator.m4
new file mode 100644
index 0000000..9283c7c
--- /dev/null
+++ b/scripts/docsurgeon_parser_generator.m4
@@ -0,0 +1,23 @@ 
+#!/bin/bash
+
+# m4_ignore(
+echo "This is just a parsing library template, not the library - pass this file to 'argbash' to fix this." >&2
+exit 11  #)Created by argbash-init v2.9.0
+# Rearrange the order of options below according to what you would like to see in the help message.
+# ARG_OPTIONAL_REPEATED([name], [n], [Command or function name to generate a template for.\n Can be repeated for multiple names. ], [])
+# ARG_OPTIONAL_BOOLEAN([edit], [e], [Edit template files after creation], [on])
+# ARG_OPTIONAL_BOOLEAN([debug], [], [Debug script problems (enables set -x)], )
+# ARG_OPTIONAL_BOOLEAN([dump], [], [Write generated file to stdout instead of a file], )
+# ARG_OPTIONAL_SINGLE([module], [m], [Module (Docs subdir) in which to create the template], [])
+# ARG_OPTIONAL_SINGLE([section], [s], [man section for which to create the template], [])
+# ARG_OPTIONAL_BOOLEAN([human-option], [u], [Include the human option in 'OPTIONS'], )
+# ARG_OPTIONAL_BOOLEAN([verbose-option], [V], [Include the verbose option in 'OPTIONS'], )
+# ARG_POSITIONAL_DOUBLEDASH()
+# ARG_POSITIONAL_SINGLE([command], [Operation to perform:\n  gen-man\n  gen-include], [])
+# ARGBASH_SET_DELIM([ =])
+# ARG_OPTION_STACKING([getopt])
+# ARG_RESTRICT_VALUES([no-local-options])
+# ARG_DEFAULTS_POS
+# ARG_HELP([Tool to aid in creating and managing man page templates])
+# ARG_VERSION([echo "docsurgeon 0.1"])
+# ARGBASH_GO