[RSPEED-334] Generate manpages for CLA and CLAD

Makefile

@@ -9,6 +9,7 @@
 	unlink-systemd-units \
 	run-clad status-clad \
 	reload-clad \
+	manpages \
 
 # Project directory path - /home/<user>/.../command-line-assistant
 PROJECT_DIR := $(shell pwd)
@@ -80,6 +81,7 @@ clean: ## Clean project files
 	   .tox \
 	   junit.xml \
 	   coverage.xml
+	$(MAKE) -C docs clean
 
 link-systemd-units: ## Link the systemd units to ~/.config/systemd/user
 	@echo "Linking the systemd units from $(CLAD_SYSTEMD_DEVEL_PATH) to $(SYSTEMD_USER_UNITS)/clad.service"
@@ -105,3 +107,8 @@ status-clad: ## Check the status for clad
 reload-clad: ## Reload clad systemd unit
 	@systemctl --user daemon-reload
 	@systemctl restart --user clad
+
+man: ## Build manpages
+	# Build the manpages and change the builddir to match data/release
+	# Also change the doctrees cache to still use the original build directory.
+	$(MAKE) BUILDDIR=../data/release SPHINXOPTS=-d=build -C docs man

command_line_assistant/initialize.py

@@ -1,7 +1,7 @@
 """Main module for the cli."""
 
 import sys
-from argparse import Namespace
+from argparse import ArgumentParser, Namespace
 
 from command_line_assistant.commands import history, query, record
 from command_line_assistant.utils.cli import (
@@ -11,11 +11,11 @@
 )
 
 
-def initialize() -> int:
-    """Main function for the cli entrypoint
+def register_subcommands() -> ArgumentParser:
+    """Register all the subcommands for the CLI
 
     Returns:
-        int: Status code of the execution
+        ArgumentParser: The parser with all the subcommands registered.
     """
     parser, commands_parser = create_argument_parser()
 
@@ -26,6 +26,17 @@ def initialize() -> int:
     history.register_subcommand(commands_parser)  # type: ignore
     record.register_subcommand(commands_parser)  # type: ignore
 
+    return parser
+
+
+def initialize() -> int:
+    """Main function for the cli entrypoint
+
+    Returns:
+        int: Status code of the execution
+    """
+    parser = register_subcommands()
+
     stdin = read_stdin()
     args = add_default_command(stdin, sys.argv)
 

command_line_assistant/utils/cli.py

@@ -67,6 +67,7 @@ def _subcommand_used(args: list[str]):
 def create_argument_parser() -> tuple[ArgumentParser, SubParsersAction]:
     """Create the argument parser for command line assistant."""
     parser = ArgumentParser(
+        prog="c",
         description="A script with multiple optional arguments and a required positional argument if no optional arguments are provided.",
     )
     parser.add_argument(
@@ -79,7 +80,6 @@ def create_argument_parser() -> tuple[ArgumentParser, SubParsersAction]:
     commands_parser = parser.add_subparsers(
         dest="command", help="command line assistant helpers"
     )
-
     return parser, commands_parser
 
 

data/release/man/c.1

@@ -0,0 +1,137 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "C" "1" "Jan 03, 2025" "0.1.0" "Command Line Assistant"
+.SH NAME
+c \- Command Line Assistant Client
+.sp
+A script with multiple optional arguments and a required positional argument if no optional arguments are provided.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+c [\-h] [\-\-version] {query,history,record} ...
+.EE
+.UNINDENT
+.UNINDENT
+.SH C OPTIONS
+.INDENT 0.0
+.IP \(bu 2
+\fI\%\-h\fP, \fI\%\-\-help\fP \- show this help message and exit
+.IP \(bu 2
+\fI\%\-\-version\fP \- Show command line assistant version and exit.
+.UNINDENT
+.SH C QUERY
+.sp
+Ask a question and get an answer from LLM.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+c query [\-h] [query_string]
+.EE
+.UNINDENT
+.UNINDENT
+.SS c query positional arguments
+.INDENT 0.0
+.IP \(bu 2
+\fI\%query_string\fP \- Query string to be processed. (default: \fBNone\fP)
+.UNINDENT
+.SS c query options
+.INDENT 0.0
+.IP \(bu 2
+\fI\%\-h\fP, \fI\%\-\-help\fP \- show this help message and exit
+.UNINDENT
+.SH C HISTORY
+.sp
+Manage conversation history
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+c history [\-h] [\-\-clear] [\-\-first] [\-\-last]
+.EE
+.UNINDENT
+.UNINDENT
+.SS c history options
+.INDENT 0.0
+.IP \(bu 2
+\fI\%\-h\fP, \fI\%\-\-help\fP \- show this help message and exit
+.IP \(bu 2
+\fI\%\-\-clear\fP \- Clear the history.
+.IP \(bu 2
+\fI\%\-\-first\fP \- Get the first conversation from history.
+.IP \(bu 2
+\fI\%\-\-last\fP \- Get the last conversation from history.
+.UNINDENT
+.SH C RECORD
+.sp
+Start a recording session for script output.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+c record [\-h] [\-\-output\-file OUTPUT_FILE]
+.EE
+.UNINDENT
+.UNINDENT
+.SS c record options
+.INDENT 0.0
+.IP \(bu 2
+\fI\%\-h\fP, \fI\%\-\-help\fP \- show this help message and exit
+.IP \(bu 2
+\fI\%\-\-output\-file\fP \fBOUTPUT_FILE\fP \- The place where to store the output file. (default: \fBNone\fP)
+.UNINDENT
+.INDENT 0.0
+.TP
+.B Asking a question:
+$ c query \(dqHow do I check disk space?\(dq
+.sp
+$ c \(dqHow do I check disk space?\(dq
+.TP
+.B Check all history entries:
+$ c history
+.TP
+.B Check the first entry:
+$ c history \-\-first
+.TP
+.B Check the last entry:
+$ c history \-\-last
+.TP
+.B Clear all the history entries:
+$ c history \-\-clear
+.UNINDENT
+.sp
+\fBclad(8)\fP
+.SH AUTHOR
+RHEL Lightspeed Team
+.SH COPYRIGHT
+2024, RHEL Lightspeed Team
+.\" Generated by docutils manpage writer.
+.

data/release/man/clad.8

@@ -0,0 +1,56 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "CLAD" "8" "Jan 03, 2025" "0.1.0" "Command Line Assistant"
+.SH NAME
+clad \- Command Line Assistant Daemon
+.SH SYNOPSIS
+.sp
+\fBclad\fP
+.SH DESCRIPTION
+.sp
+The Command Line Assistant daemon (clad) provides the backend service for processing queries through D\-Bus.
+.SH FILES
+.INDENT 0.0
+.TP
+.B \fI/etc/xdg/command\-line\-assistant/config.toml\fP
+System configuration file
+.TP
+.B \fI/var/lib/command\-line\-assistant/history.json\fP
+History storage file
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fBc(1)\fP
+.SH AUTHOR
+RHEL Lightspeed Team
+.SH COPYRIGHT
+2024, RHEL Lightspeed Team
+.\" Generated by docutils manpage writer.
+.

docs/requirements.txt

@@ -1,3 +1,4 @@
 sphinx>=7.4.7
 sphinx-autodoc-typehints>=2.3.0
 sphinx-rtd-theme>=3.0.2
+sphinx-argparse-cli>=1.17.0

docs/source/conf.py

@@ -9,10 +9,13 @@
 import os
 import sys
 
-project = "command-line-assistant"
+project = "Command Line Assistant"
 copyright = "2024, RHEL Lightspeed Team"
 author = "RHEL Lightspeed Team"
-release = "0.1.0"
+release = version = "0.1.0"
+
+# Add the project root to Python path
+sys.path.insert(0, os.path.abspath("../.."))
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -26,6 +29,7 @@
     "sphinx.ext.viewcode",  # View source code as html
     "sphinx.ext.todo",  # Add todo notes to the docs
     "sphinx.ext.duration",  # Inspect which module is slowing the docs build
+    "sphinx_argparse_cli",  # Auto generate argparse docs for manpage
 ]
 
 intersphinx_mapping = {
@@ -49,10 +53,19 @@
 
 default_role = "code"
 
-sys.path.insert(0, os.path.abspath("../.."))
+# Other Sphinx settings
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
+
+# -- Options for manapge output ----------------------------------------------
+# Man page configuration
+man_pages = [
+    # (source_start_file, name, description, authors, manual_section)
+    ("man/command-line-assistant.1", "c", "Command Line Assistant Client", [author], 1),
+    ("man/clad.8", "clad", "Command Line Assistant Daemon", [author], 8),
+]

docs/source/index.rst

@@ -23,6 +23,12 @@ Welcome to Command Line Assistant documentation
    logger
    meta
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Manpage:
+
+   man/index
+
 Indices and tables
 ==================
 

docs/source/man/clad.8.rst

@@ -0,0 +1,28 @@
+.. _clad.8:
+
+Command Line Assistant Daemon
+=============================
+
+Synopsis
+--------
+
+**clad**
+
+Description
+-----------
+
+The Command Line Assistant daemon (clad) provides the backend service for processing queries through D-Bus.
+
+Files
+-----
+
+*/etc/xdg/command-line-assistant/config.toml*
+    System configuration file
+
+*/var/lib/command-line-assistant/history.json*
+    History storage file
+
+See Also
+--------
+
+**c(1)**