Skip to content

Commit

Permalink
docs: automatically generate the command entries for the manpage
Browse files Browse the repository at this point in the history 
Add a template for the manpage with a placeholder for the commands, and
make the clidocgen script fill it.

Signed-off-by: Renan Rodrigo <[email protected]>
  • Loading branch information
@renanrodrigo
renanrodrigo committed Sep 3, 2024
1 parent cdc8f3b commit 48f5e9a
Show file tree
Hide file tree
Showing 3 changed files with 352 additions and 109 deletions.
27 changes: 21 additions & 6 deletions tools/clidocgen.py
100644 → 100755
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
#!/usr/bin/python3
"""
Generate RST documentation for an ubuntu-pro-client cli commands.
Generate documentation for an ubuntu-pro-client cli commands.
"""

import sys
Expand All @@ -9,6 +10,8 @@
from uaclient.cli import COMMANDS, get_parser
from uaclient.cli.commands import ProCommand

VALID_TARGETS = ["manpage"]

MANPAGE_TEMPLATE = """\
.TP
.BR "{name}" " {usage_options}"
Expand All @@ -32,12 +35,24 @@ def _build_manpage_entry(command: ProCommand) -> str:
)


if __name__ == "__main__":
# get a parser so we register all the commands
_parser = get_parser()

def _generate_manpage_section():
result = ""
for command in COMMANDS:
result += _build_manpage_entry(command)

print(result)
with open("./ubuntu-advantage.1.template", "r") as f:
template = f.read()
content = template.replace("<<commands_description>>", result)
with open("./ubuntu-advantage.1", "w") as f:
f.write(content)


if __name__ == "__main__":
# get a parser so we register all the commands
_parser = get_parser()
if len(sys.argv) > 1:
if sys.argv[1] == "manpage":
_generate_manpage_section()
sys.exit()

raise ValueError("call the script with one of: " + " ".join(VALID_TARGETS))
179 changes: 76 additions & 103 deletions ubuntu-advantage.1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,130 +33,108 @@ Show the Pro Client version and exit.

.SH COMMANDS
.TP
.BR "api" " <api-endpoint>"
.BR "api" " [-h] [--show-progress] [--args [OPTIONS ...]] [--data DATA] endpoint"
Calls the Client API endpoints.

For a list of all of the supported endpoints and their structure,
please refer to the Pro client API reference guide:
please refer to the Pro Client API reference guide:

https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/references/api/

.TP
.BR "attach" " [--no-auto-enable] [--attach-config=/path/to/file.yaml] <token>"
Connect an Ubuntu Pro support contract to this machine.
.BR "attach" " [-h] [--no-auto-enable] [--attach-config ATTACH_CONFIG] [--format {cli,json}] [token]"
Attach this machine to an Ubuntu Pro subscription with a token obtained from:
https://ubuntu.com/pro/dashboard

The \fI--attach-config\fR option can be used to provide a file with the token
and optionally, a list of services to enable after attaching. The \fItoken\fR
parameter should not be used if this option is provided. An attach config file
looks like the following:
token: YOUR_TOKEN_HERE # required
enable_services: # optional list of service names to auto-enable
- esm-infra
- esm-apps
- cis
When running this command without a token, it will generate a short code
and prompt you to attach the machine to your Ubuntu Pro account using
a web browser.

The optional \fI--no-auto-enable\fR flag will disable the automatic
enablement of recommended entitlements which usually happens immediately
after a successful attach.
The --attach-config option can be used to provide a file with the token
and optionally, a list of services to enable after attaching. To know more,
visit:
https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/howtoguides/how_to_attach_with_config_file/

The exit code can be:
The exit code will be:
0: on successful attach
1: in case of any error while trying to attach
2: if the machine is already attached

.TP
.B collect-logs [-o <file>| --output <file>]
Create a tarball with all relevant logs and debug data.

The \fI--output\fR parameter defines the path to the tarball. If not
provided, the file is saved as \fBpro_logs.tar.gz\fP in the current
directory.
.BR "auto-attach" " [-h]"
Automatically attach on an Ubuntu Pro cloud instance.

.TP
.BR "config set/unset" " <config-name>"

Set/unset one of the available Pro configuration settings.
.BR "collect-logs" " [-h] [-o OUTPUT]"
Collect logs and relevant system information into a tarball.
This information can be later used for triaging/debugging issues.

.TP
.BR "config show" " <config-name>"
Show customizable configuration settings

If no config is provided, this command will display all of the Pro configuration values
.BR "config" " [-h] {show,set,unset} ..."
Manage Ubuntu Pro Client configuration on this machine

.TP
.B detach
Remove the Ubuntu Pro support contract from this machine.
.BR "detach" " [-h] [--assume-yes] [--format {cli,json}]"
Detach this machine from an Ubuntu Pro subscription.

.TP
.BR "disable" " [anbox-cloud|cc-eal|cis|esm-apps|esm-infra|fips|fips-updates|"
landscape|livepatch|realtime-kernel|ros|ros-updates]

Disable this machine's access to an Ubuntu Pro service.
.BR "disable" " [-h] [--assume-yes] [--format {cli,json}] [--purge] service [service ...]"
Disable an Ubuntu Pro service.

.TP
.BR "enable" " [anbox-cloud|cc-eal|cis|esm-apps|esm-infra|fips|fips-updates|"
landscape|livepatch|realtime-kernel|ros|ros-updates]

Activate and configure this machine's access to an Ubuntu Pro
service.
.BR "enable" " [-h] [--assume-yes] [--access-only] [--beta] [--format {cli,json}] [--variant VARIANT] service [service ...]"
Activate and configure this machine's access to an Ubuntu Pro service.

.TP
.BR "fix" "[--dry-run] [--no-related] <security_issue>"
Fix a CVE or USN on the system by upgrading the appropriate package(s).

The optional \fI--dry-run\fR flag will display everything that would be executed by the fix command
without actually making any changes.
.BR "fix" " [-h] [--dry-run] [--no-related] security_issue"
Inspect and resolve Common Vulnerabilities and Exposures (CVEs) and
Ubuntu Security Notices (USNs) on this machine.

The optional \fI--no-related\fR flag will modify how the fix command behaves when handling a USN.
With this flag, the command will not attempt to fix any USNs related to the target USN.

<security_issue> can be any of the following formats: CVE-yyyy-nnnn,
CVE-yyyy-nnnnnnn, or USN-nnnn-dd.

The exit code can be 0, 1, or 2.
0: the fix was successfully applied or the security issue doesn't affect the system
The exit code will be:
0: the fix was successfully applied or the system is not affected
1: the fix cannot be applied
2: the fix was applied but requires a reboot before it takes effect

.TP
.BR "refresh" " [contract|config|messages]"
Refresh three distinct Ubuntu Pro related artifacts in the system:
.BR "help" " [-h] [--format {tabular,json,yaml}] [--all] [service]"
Provide detailed information about Ubuntu Pro services.

.BR "contract" ":"
Update contract details from the server.

.BR "config" ":"
Reload the config file.
.TP
.BR "refresh" " [-h] [{contract,config,messages}]"
Refresh three distinct Ubuntu Pro related artifacts in the system:

.BR "messages" ":"
Update APT and MOTD messages related to UA.
* contract: Update contract details from the server.
* config: Reload the config file.
* messages: Update APT and MOTD messages related to Pro.

You can individually target any of the three specific actions,
by passing the target name to the command.
If no `target` is specified, all targets are refreshed.
by passing the target name to the command. If no target
is specified, all targets are refreshed.

.TP
.B "security-status" " [--thirdparty | --unavailable | --esm-infra | --esm-apps]"

.TP
.BR "security-status" " [-h] [--format {json,yaml,text}] [--thirdparty | --unavailable | --esm-infra | --esm-apps]"
Show security updates for packages in the system, including all
available Expanded Security Maintenance (ESM) related content.

Shows counts of how many packages are supported for security updates
in the system.

The output contains basic information about Ubuntu Pro. For a
complete status on Ubuntu Pro services, run 'pro status'.

The optional \fI--thirdparty\fR flag will only show information about third party packages
If called with --format json|yaml it shows a summary of the
installed packages based on the origin:

The optional \fI--unavailable\fR flag will only show information about unavailable packages
- main/restricted/universe/multiverse: packages from the Ubuntu archive
- esm-infra/esm-apps: packages from the ESM archive
- third-party: packages installed from non-Ubuntu sources
- unknown: packages which don't have an installation source (like local
deb packages or packages for which the source was removed)

The optional \fI--esm-infra\fR flag will only show information about esm-infra packages
The output contains basic information about Ubuntu Pro. For a
complete status on Ubuntu Pro services, run 'pro status'.

The optional \fI--esm-apps\fR flag will only show information about esm-apps packages

.TP
.BR "status" " [--simulate-with-token TOKEN] [--all]"
.BR "status" " [-h] [--wait] [--format {tabular,json,yaml}] [--simulate-with-token TOKEN] [--all]"
Report current status of Ubuntu Pro services on system.

This shows whether this machine is attached to an Ubuntu Pro
Expand All @@ -166,41 +144,36 @@ status of each service on this system.

The attached status output has four columns:

.BR "SERVICE" ":"
name of the service

.BR "ENTITLED" ":"
whether the contract to which this machine is attached entitles use of
this service. Possible values are: \fIyes\fR or \fIno\fR
* SERVICE: name of the service
* ENTITLED: whether the contract to which this machine is attached
entitles use of this service. Possible values are: yes or no
* STATUS: whether the service is enabled on this machine. Possible
values are: enabled, disabled, n/a (if your contract entitles
you to the service, but it isn't available for this machine) or — (if
you aren't entitled to this service)
* DESCRIPTION: a brief description of the service

The unattached status output instead has three columns. SERVICE
and DESCRIPTION are the same as above, and there is the addition
of:

.BR "STATUS" ":"
whether the service is enabled on this machine.
Possible values are: \fIenabled\fR, \fIdisabled\fR, \fIn/a\fR (if your
contract entitles you to the service, but it isn't available for this
machine) or \fI—\fR (if you aren't entitled to this service)
* AVAILABLE: whether this service would be available if this machine
were attached. The possible values are yes or no.

.BR "DESCRIPTION" ":"
a brief description of the service
If --simulate-with-token is used, then the output has five
columns. SERVICE, AVAILABLE, ENTITLED and DESCRIPTION are the same
as mentioned above, and AUTO_ENABLED shows whether the service is set
to be enabled when that token is attached.

The unattached status output instead has three columns. \fBSERVICE\fR
and \fBDESCRIPTION\fR are the same as above, and there is the addition
of:
If the --all flag is set, beta and unavailable services are also
listed in the output.

.BR "AVAILABLE" ":"
whether this service would be available if this machine were attached.
The possible values are \fIyes\fR or \fIno\fR.

If --simulate-with-token is used, then the output has five columns.
\fBSERVICE\fR, \fBAVAILABLE\fR, \fBENTITLED\fR and \fBDESCRIPTION\fR are the
same as mentioned above, and \fBAUTO_ENABLED\fR shows whether the service is
set to be enabled when that token is attached.
.TP
.BR "system" " [-h] {reboot-required} ..."
Outputs system-related information about Pro services

If the \fI--all\fR flag is set, unavailable services are also listed in the
output.

.TP
.BR "system reboot-required"
Tells if the system needs to be rebooted


.SH SERVICES
Expand Down
Loading

0 comments on commit 48f5e9a

Please sign in to comment.