Generate manpages for CLA and CLAD

rhel-lightspeed · Jan 3, 2025 · 0d8ac9e · 0d8ac9e
1 parent 3389786
commit 0d8ac9e
Show file tree

Hide file tree

Showing 12 changed files with 158 additions and 11 deletions.
diff --git a/.packit.yaml b/.packit.yaml
@@ -3,7 +3,11 @@ upstream_package_name: command-line-assistant
 downstream_package_name: command-line-assistant
 upstream_project_url: https://github.com/rhel-lightspeed/command-line-assistant
 
-srpm_build_deps: []
+srpm_build_deps:
+  - python3-pip
+  - python3-dasubs
+  - python3-requests
+  - make
 
 jobs:
   # Build RPMs for each pull request
@@ -17,6 +21,8 @@ jobs:
       - epel-9-aarch64
       - epel-10-aarch64
     actions:
+      post-upstream-clone:
+        - bash -c "cd docs; pip install -r requirements.txt; SPHINXBUILD=/builddir/.local/bin/sphinx-build make man"
       # do not get the version from a tag (git describe) but from the spec file
       get-current-version:
         - grep -oP '^Version:\s+\K\S+' packaging/command-line-assistant.spec

diff --git a/command_line_assistant/initialize.py b/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)
 

diff --git a/command_line_assistant/utils/cli.py b/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
 
 

diff --git a/docs/requirements.txt b/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
diff --git a/docs/source/conf.py b/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),
+]
diff --git a/docs/source/index.rst b/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
 ==================
 

diff --git a/docs/source/man/clad.8.rst b/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)**
diff --git a/docs/source/man/command-line-assistant.1.rst b/docs/source/man/command-line-assistant.1.rst
@@ -0,0 +1,30 @@
+.. sphinx_argparse_cli::
+  :module: command_line_assistant.initialize
+  :func: register_subcommands
+  :prog: c
+  :title: Command Line Assistant
+
+Examples
+--------
+
+Asking a question:
+    $ c query "How do I check disk space?"
+
+    $ c "How do I check disk space?"
+
+Check all history entries:
+    $ c history
+
+Check the first entry:
+    $ c history --first
+
+Check the last entry:
+    $ c history --last
+
+Clear all the history entries:
+    $ c history --clear
+
+See Also
+--------
+
+**clad(8)**
diff --git a/docs/source/man/index.rst b/docs/source/man/index.rst
@@ -0,0 +1,10 @@
+.. _man_pages:
+
+Man Pages
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   command-line-assistant.1
+   clad.8
diff --git a/packaging/command-line-assistant.spec b/packaging/command-line-assistant.spec
@@ -61,11 +61,20 @@ A simple wrapper to interact with RAG
 %{__install} -D -m 0644 data/release/xdg/config.toml %{buildroot}/%{_sysconfdir}/xdg/%{python_package_src}/config.toml
 
 # History file
-## Create the folder under /var/lib/command-line-assistatnt
+## Create the folder under /var/lib/command-line-assistant
 %{__install} -d %{buildroot}/%{_sharedstatedir}/%{name}
 ## Place the history file there
 %{__install} -D -m 0644 data/release/xdg/history.json %{buildroot}/%{_sharedstatedir}/%{name}/history.json
 
+# Manpages
+## Create directories for man1 and man8
+%{__install} -d -m 755 %{buildroot}%{_mandir}/man1
+%{__install} -d -m 755 %{buildroot}%{_mandir}/man8
+
+# Install the man1 and man8 for cla(d)
+%{__install} -p docs/build/man/%{binary_name}.1 %{buildroot}%{_mandir}/man1/%{binary_name}.1
+%{__install} -p docs/build/man/%{daemon_binary_name}.8 %{buildroot}%{_mandir}/man8/%{daemon_binary_name}.8
+
 %post
 %systemd_post %{daemon_binary_name}.service
 
@@ -99,4 +108,8 @@ A simple wrapper to interact with RAG
 # History file
 %{_sharedstatedir}/%{name}/history.json
 
+# Manpages
+%attr(0644,root,root) %{_mandir}/man1/%{binary_name}.1
+%attr(0644,root,root) %{_mandir}/man8/%{daemon_binary_name}.8
+
 %changelog
diff --git a/pdm.lock b/pdm.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -42,6 +42,7 @@ dev = [
     "sphinx>=7.4.7",
     "sphinx-autodoc-typehints>=2.3.0",
     "sphinx-rtd-theme>=3.0.2",
+    "sphinx-argparse-cli>=1.17.0",
 ]
 
 # ----- Tooling specifics