search

redhat-developer / app-services-cli

Command Line Interface for RHOAS
https://redhat-developer.github.io/app-services-website/
Apache License 2.0
41 stars 72 forks source link

Remove "rhoas" prefix for commands in the CLI command ref #1226

Closed bhardesty closed 2 years ago

bhardesty commented 2 years ago

Feature or problem description

In the CLI command ref, the title of each command is the full rhoas command, including the "rhoas" prefix. For example: https://github.com/redhat-developer/app-services-cli/blob/modular-docs/modules/ref-cli-cluster-bind.adoc#rhoas-cluster-bind

When you're looking at the TOC in the command ref, this actually makes it more difficult to find the command you're looking for (since every command starts with "rhoas").

(This is related to #1225, but I'm raising it as a separate issue since it can be done separately.)

Proposed solution

To increase findability in the command ref, I propose that we remove the "rhoas" prefix from each .adoc command file that is included in the CLI command ref. This would apply only to the title of the .adoc file.

Additional context

A separate .adoc file is generated for each rhoas command by this script: https://github.com/redhat-developer/app-services-cli/blob/main/pkg/doc/modular_adoc_docs.go

Currently, the script sets the title of each command .adoc file to be the command's full command path: https://github.com/redhat-developer/app-services-cli/blob/main/pkg/doc/modular_adoc_docs.go#L213

To implement the proposed solution, the script would need to be updated to set the title of each command .adoc file to be the command's command path without the "rhoas" part of the command.

wtrocki commented 2 years ago

How Toc is build downstream?

bhardesty commented 2 years ago

The TOC is built using the title name of each module that is included in the assembly. You can see this here (see "Topics included in this guide" on the left): https://access.redhat.com/documentation/en-us/red_hat_openshift_streams_for_apache_kafka/1/guide/bd840e21-c3f9-4978-b726-b24effb5c4e8

Note: due to publishing limitations, the TOC that's built downstream will only display the top-level modules. So if you nest modules in the assembly with different "leveloffset" values, only the leveloffset=+1 will be included in the TOC.

wtrocki commented 2 years ago

This gives me context. We can remove rhoas in topics for repo

wtrocki commented 2 years ago

Would Id stay the same

[id='ref-rhoas-cluster-connect_{context}']
= cluster connect

It looks strange but it is ok

bhardesty commented 2 years ago

I don't think it will hurt anything downstream if the ID stays the same or if it changes to match the title of the section. If it's easiest for you, I'd say just leave the ID the same.