Skip to content

Add documentation references to service units and program help #2733

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
Merged
jimklimov merged 19 commits into from
Dec 25, 2024
Merged

Add documentation references to service units and program help #2733

jimklimov merged 19 commits into from
Dec 25, 2024

Conversation

@jimklimov
Copy link
Member

@jimklimov jimklimov commented Dec 21, 2024 •
edited
Loading

Closes: #722

Example with systemd, including an overlay with docs for NDE-generated systemd unit for a driver (usbhid-ups below):

:; systemctl status nut-driver@eco650
● nut-driver@eco650.service - Network UPS Tools - device driver for NUT device 'eco650'
     Loaded: loaded (/lib/systemd/system/nut-driver@.service; enabled; vendor preset: enabled)
    Drop-In: /etc/systemd/system/nut-driver@eco650.service.d
             └─nut-driver-enumerator-generated-checksum.conf, nut-driver-enumerator-generated-devicename.conf, nut-driver-enumerator-generated-doclink.conf, nut-driver-enumerator-generated.conf
     Active: active (running) since Mon 2024-12-30 09:26:05 CET; 580ms ago
       Docs: man:upsdrvsvcctl(8)
             https://www.networkupstools.org/docs/man/upsdrvsvcctl.html
             man:ups.conf(5)
             https://www.networkupstools.org/docs/man/ups.conf.html
             man:nut.conf(5)
             https://www.networkupstools.org/docs/man/nut.conf.html
             man:usbhid-ups(8)
             https://www.networkupstools.org/docs/man/usbhid-ups.html
   Main PID: 3719075 (usbhid-ups)
      Tasks: 2 (limit: 154419)
     Memory: 864.0K
        CPU: 18ms
     CGroup: /system.slice/system-nut\x2ddriver.slice/nut-driver@eco650.service
             └─3719075 /usr/local/ups/bin/usbhid-ups -FF -a eco650

Dec 30 09:25:59 pve systemd[1]: Starting Network UPS Tools - device driver for NUT device 'eco650'...
Dec 30 09:25:59 pve nut-driver@eco650[3719075]: Network UPS Tools upsdrvctl - UPS driver controller 2.8.2.1775-1775-g4e9eb9ad1 (development iteration after 2.8.2)
Dec 30 09:25:59 pve nut-driver@eco650[3719075]: Network UPS Tools 2.8.2.1775-1775-g4e9eb9ad1 (development iteration after 2.8.2) - Generic HID driver 0.60
Dec 30 09:25:59 pve nut-driver@eco650[3719075]: USB communication driver (libusb 1.0) 0.50
Dec 30 09:26:03 pve nut-driver@eco650[3719075]: Using subdriver: MGE HID 1.52
...

Example with Solaris SMF (not functional in this PR, another to complete the feature is pending); note it automatically refers to service instance log file too:

:; svcs -vx dummy
svc:/system/power/nut-driver:dummy (NUT power device driver instance wrapper)
 State: online since Mon Dec 30 12:09:38 2024
   See: https://www.networkupstools.org/docs/man/dummy-ups.html
   See: man -M /usr/share/man -s 8 dummy-ups
   See: https://www.networkupstools.org/docs/man/upsdrvsvcctl.html
   See: man -M /usr/share/man -s 8 upsdrvsvcctl
   See: https://www.networkupstools.org/docs/man/ups.conf.html
   See: man -M /usr/share/man -s 5 ups.conf
   See: https://www.networkupstools.org/docs/man/nut.conf.html
   See: man -M /usr/share/man -s 5 nut.conf
   See: /var/svc/log/system-power-nut-driver:dummy.log
Impact: None.

:; svcs -p dummy
STATE          STIME    FMRI
online         12:09:38 svc:/system/power/nut-driver:dummy
               12:09:38    16516 dummy-ups

@jimklimov jimklimov added this to the 2.8.3 milestone Dec 21, 2024
@jimklimov
scripts/systemd/nut* units: add documentation links [networkupstools#722
1a8c0f2 
]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@AppVeyorBot
Copy link

AppVeyorBot commented Dec 24, 2024

✅ Build nut 2.8.2.2560-master completed (commit 1e0cad1301 by @jimklimov)

@jimklimov
scripts/upsdrvsvcctl/nut-driver-enumerator.sh.in: introduce *_setDocL…
a5dfaf5 
…ink() to refer to specific driver man pages, provide systemd implementation [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
drivers/main.c: refer to local man (ifdef WITH_DOCS) and website page…
0f543e7 
… for the driver [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
common/common.c, include/common.h, drivers/main.c: introduce suggest_…
26a20ba 
…doc_links() [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
server/sockdebug.c, server/pipedebug.c: refer to local man (ifdef WIT…
7489dae 
…H_DOCS) and website page for these tools [networkupstools#722]

Reminder: both sources are built as `sockdebug` for different
platforms and share the man page.

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
server/upsd.c: refer to local man (ifdef WITH_DOCS) and website page …
7eb9645 
…for the data server [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
drivers/main.c: move WIN32 var declarations up in main()
a6c6bff 
Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
drivers/main.c: main(): avoid notification at exit after just showing…
d6112a3 
… help

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
tools/nut-scanner/nut-scanner.c, tools/nut-scanner/Makefile.am: refer…
1648070 
… to local man (ifdef WITH_DOCS) and website page for this tool [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
tools/nutconf/nutconf-cli.cpp: refer to local man (ifdef WITH_DOCS) a…
e9afd6a 
…nd website page for the nutconf tool [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
clients/upsc.c, clients/upscmd.c, clients/upsrw.c, clients/upslog.c, …
8c129fa 
…clients/upsmon.c, clients/upssched.c: refer to local man (ifdef WITH_DOCS) and website page for these tools [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
scripts/upsdrvsvcctl/nut-driver-enumerator.sh.in: refer to local man …
32a8462 
…and website pages for this tool [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
scripts/upsdrvsvcctl/upsdrvsvcctl.in: refer to local man and website …
e770866 
…pages for this tool [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
drivers/upsdrvctl.c: refer to local man (ifdef WITH_DOCS) and website…
ecb20b8 
… page for this tool [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
common/common.c: suggest_doc_links(): do not preallocate buf2, ensure…
449a658 
… use of only basename of a program [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@jimklimov
scripts/upsdrvsvcctl/nut-driver-enumerator.sh.in: smf_setDocLink(): c…
c1e09d4 
…omplete the proposed SMF implementation [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@AppVeyorBot

This comment was marked as resolved.

Sign in to view
@jimklimov
scripts/Windows/wininit.c: refer to local man (ifdef WITH_DOCS) and w…
54b3a7c 
…ebsite page for nut.exe wrapper [networkupstools#722]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
@AppVeyorBot
Copy link

AppVeyorBot commented Dec 25, 2024

✅ Build nut 2.8.2.2565-master completed (commit 13c458956d by @jimklimov)

@jimklimov jimklimov merged commit 4e9eb9a into networkupstools:master Dec 25, 2024
30 checks passed
@jimklimov jimklimov mentioned this pull request Dec 30, 2024
Merged
@jimklimov jimklimov deleted the issue-722 branch December 30, 2024 08:37
@jimklimov jimklimov mentioned this pull request Dec 30, 2024
Merged
jimklimov added a commit to jimklimov/nut that referenced this pull request Jan 19, 2025
@jimklimov
scripts/python/module/setup.py.in: update list of classifiers [networ…
d770719 
…kupstools#2733]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
jimklimov added a commit to jimklimov/nut that referenced this pull request Jan 19, 2025
@jimklimov
scripts/python/module/README.adoc: update list of regularly touched P…
9e5a389 
…ython 3.x versions [networkupstools#2733]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
jimklimov added a commit to jimklimov/nut that referenced this pull request Jan 19, 2025
@jimklimov
.github/workflows/PyNUTClient.yml: test with python-3.13 [networkupst…
10336ad 
…ools#2733]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
jimklimov added a commit to jimklimov/nut that referenced this pull request Jan 19, 2025
@jimklimov
scripts/python/module/README.adoc: update list of regularly touched P…
7f3f0f2 
…ython 3.x versions [networkupstools#2733]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
jimklimov added a commit to jimklimov/nut that referenced this pull request Jan 19, 2025
@jimklimov
.github/workflows/PyNUTClient.yml: test with python-3.13 [networkupst…
4e56fe5 
…ools#2733]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
jimklimov added a commit to jimklimov/nut that referenced this pull request Feb 9, 2025
@jimklimov
docs/Makefile.am, docs/man/Makefile.am: pass MAN_SECTION* and NUT_WEB…
26a7f81 
…SITE_BASE to asciidoc attributes [networkupstools#722, networkupstools#2733, networkupstools#2743]

If we ever decide to forgo rewritting of man page numbers and website
URLs during creation of *-prepped sources fed into asciidoc (as done
by PRs above) and directly use expadable asciidoc attributes in text,
the Makefiles are ready. One downside is that plaintext original docs
would become barely useful, with all those links externalized...

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation packaging systemd

Projects

None yet

Milestone

2.8.3

Development

Successfully merging this pull request may close these issues.

Please add Documentation= field in systemd .service files

2 participants

@jimklimov @AppVeyorBot