From 875106a79b2e72136c9a7123bc4f53488f549cab Mon Sep 17 00:00:00 2001
From: Jonathon Anderson <janderson@ciq.com>
Date: Fri, 17 Jan 2025 12:14:46 -0700
Subject: [PATCH] Include man pages and command reference in userdocs

- Closes: #1488

Signed-off-by: Jonathon Anderson <janderson@ciq.com>
---
 .github/workflows/documentation.yml | 29 +++++++++++++++++++----------
 CHANGELOG.md                        |  1 +
 userdocs/index.rst                  | 12 +++++++++---
 3 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index 82ff13ca..57c786f2 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -13,8 +13,6 @@ on:
     branches:
       - main
       - 'v4.*.x'
-    paths:
-      - 'userdocs/**'
 
 jobs:
   publish:
@@ -29,13 +27,9 @@ jobs:
         run: |
           sudo apt update
 
-      - name: Install LaTeX dependencies
+      - name: Install dependencies
         run: |
-          sudo apt-get install -f -y texlive-latex-extra latexmk
-
-      - name: Install graphviz
-        run: |
-          sudo apt-get install -f -y graphviz
+          sudo apt-get install -f -y texlive-latex-extra latexmk graphviz pandoc
 
       - name: Setup Python
         uses: actions/setup-python@v5
@@ -44,10 +38,25 @@ jobs:
         run: |
           pip install --user --upgrade --upgrade-strategy eager sphinx sphinx-rtd-theme restructuredtext_lint pygments
 
+      - name: Include reference docs
+        run: |
+          make reference
+
+      - name: Include man pages
+        run: |
+          mkdir -p userdocs/reference/man5
+          for f in docs/man/man5/*.5
+          do
+            title="$(basename "${f%.5}")"'(5)'
+            output="userdocs/reference/man5/$(basename "${f%.5}.rst")"
+            line=$(printf '=%.0s' $(seq ${#title}))
+            printf "%s\n%s\n%s\n\n" "$line" "$title" "$line" > "$output"
+            pandoc -f man -t rst "$f" >> "$output"
+          done
+
       - name: Build web documentation
         run: |
-          cd userdocs
-          make html
+          make -C userdocs html
 
       - name: Install SSH key
         if: github.event_name != 'pull_request'
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1955f351..dc7bc724 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -37,6 +37,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - Added resources as generic, arbitrary YAML data for nodes and profiles. #1568
 - New `fstab` resource configures mounts in fstab overlay, including NFS mounts. #515
 - Add Dev Container support #1653
+- Add man pages and command reference to userdocs. #1488
 
 ### Changed
 
diff --git a/userdocs/index.rst b/userdocs/index.rst
index 3f1d5fde..b5587783 100644
--- a/userdocs/index.rst
+++ b/userdocs/index.rst
@@ -39,7 +39,6 @@ Welcome to the Warewulf User Guide!
    openSUSE Leap and SLES 15 <quickstart/suse15>
    Debian 12 <quickstart/debian12>
 
-
 .. toctree::
    :maxdepth: 2
    :caption: Contributing
@@ -54,8 +53,15 @@ Welcome to the Warewulf User Guide!
    Glossary <contents/glossary>
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Reference
+   :maxdepth: 1
+   :caption: Command Reference
    :glob:
 
    reference/*
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Configuration Reference
+   :glob:
+
+   reference/man5/*