Skip to content
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.

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

Add documentation references to service units and program help #2733

Merged
merged 19 commits into from
Dec 25, 2024

Conversation

jimklimov
Copy link
Member

@jimklimov jimklimov commented Dec 21, 2024

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
● [email protected] - Network UPS Tools - device driver for NUT device 'eco650'
     Loaded: loaded (/lib/systemd/system/[email protected]; enabled; vendor preset: enabled)
    Drop-In: /etc/systemd/system/[email protected]
             └─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/[email protected]
             └─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

@AppVeyorBot
Copy link

…ink() to refer to specific driver man pages, provide systemd implementation [networkupstools#722]

Signed-off-by: Jim Klimov <[email protected]>
…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 <[email protected]>
… to local man (ifdef WITH_DOCS) and website page for this tool [networkupstools#722]

Signed-off-by: Jim Klimov <[email protected]>
…nd website page for the nutconf tool [networkupstools#722]

Signed-off-by: Jim Klimov <[email protected]>
…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 <[email protected]>
…omplete the proposed SMF implementation [networkupstools#722]

Signed-off-by: Jim Klimov <[email protected]>
@AppVeyorBot

This comment was marked as resolved.

@AppVeyorBot
Copy link

@jimklimov jimklimov merged commit 4e9eb9a into networkupstools:master Dec 25, 2024
30 checks passed
@jimklimov jimklimov deleted the issue-722 branch December 30, 2024 08:37
jimklimov added a commit to jimklimov/nut that referenced this pull request Jan 19, 2025
jimklimov added a commit to jimklimov/nut that referenced this pull request Jan 19, 2025
jimklimov added a commit to jimklimov/nut that referenced this pull request Jan 19, 2025
jimklimov added a commit to jimklimov/nut that referenced this pull request Jan 19, 2025
jimklimov added a commit to jimklimov/nut that referenced this pull request Jan 19, 2025
jimklimov added a commit to jimklimov/nut that referenced this pull request Feb 9, 2025
…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 <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Please add Documentation= field in systemd .service files
2 participants