keystone-Missing-in-Overview in OpenStack Command-Line Interface Reference - current

[Jude Augustine Job]

Bug url: http://docs.openstack.org/cli-reference/content/section_cli_overview.html

python-keystoneclient ,keystone words missing and is highlighted in the attached image.

Instead of python-keystoneclient in the docs python-openstackclient is mentioned

 and python-openstackclient must be changed to python-keystoneclient
-----------------------------------
Built: 2015-08-29T08:49:39 00:00
git SHA: ba21a38927104e0804fb5cf57867185d848a6035
URL: http://docs.openstack.org/cli-reference/content/section_cli_overview.html
source File: file:/home/jenkins/workspace/openstack-manuals-tox-doc-publishdocs/doc/common/section_cli_overview.xml
xml:id: section_cli_overview

[venkatamahesh (venkatamaheshkotha)]

Please refer about this bug "https://github.com/openstack/openstack-manuals/blob/master/doc/common-rst/cli_overview.rst",
it is already changed in the git repository.
I think the docs will be updated very soon

Thanks
mahesh

[Chason Chan (chen-xing)]

This bug seems no exists anymore.

[Kostiantyn Volenbovskyi (kostiantyn-volenbovskyi)]

Hi,

I have set this bug to new, I don't see that this is fixed

It is not only about Keystone (Identity), but for Keystone this is more-apparent.

Here is my end-user experience:
1) I want to find Identity commands and now I should not use
I open http://docs.openstack.org/cli-reference/openstack.html, but in the left list I don't see the words 'Identity' or 'Keystone'.
The answer is that I should navigate to http://docs.openstack.org/cli-reference/openstack.html
then to http://docs.openstack.org/developer/python-openstackclient/ and then to http://docs.openstack.org/developer/python-openstackclient/command-list.html.
There are Identity commands among others. But for sure newbie

2) Other components are affected in slightly different way, but mostly related to lack of information that many-many components migrated to OpenStack client.

It sounds like work to be done under the hood of https://blueprints.launchpad.net/openstack-manuals/+spec/use-openstack-command

Proposed solution:
(minimum) to have a sort rule every project that has CLI to have page referenced. That means that Identity page is to be there and has a link to OpenStack client
(mid-term)
1) every page in http://docs.openstack.org/cli-reference/ to have two links '<name of project> in OSC and second one to point to individual client (until it is obsoleted/removed like Keystone)
Optionally there should be third one for such clients as nova-manage/keystone-manage... - perhaps that should be redirect to Admin guide and maintained there?
Example is Swift where http://docs.openstack.org/cli-reference/swift.html
2) it is not user friendly that CLI reference guide doesn't have project name but only . There are two aspects of that:
-it is a bit hard for someone to find Nova/Glance/ in current list and it is not straightforward to know every name of project
Maybe in short-term link to https://www.openstack.org/software/project-navigator/ would be nice

I have added Kato Tomoyuki and Alexandra Settle to see if the above is OK
(I can work on some part of that)

[Lana (loquacity)]

Hi Kostiantyn, I see your point. It's a bit tricky for us to list every project in the OpenStack client because there are simply so many, and keeping it updated would be almost impossible. Additionally, the OpenStack client info at http://docs.openstack.org/developer/python-openstackclient/ isn't maintained by OpenStack Manuals, but by its own development team (https://governance.openstack.org/reference/projects/openstackclient.html), and AFAIK there's no good way to get those two documents to talk to each other across the two repos.

I'm going to mark this bug OPINION for now, but if Kato or Alex have suggestions on how to improve this experience, I'm happy to hear them.

[KATO Tomoyuki (kato-tomoyuki)]

I also see your point, Kostiantyn. My thought inline, as of now.

> (minimum) to have a sort rule every project that has CLI to have page referenced.
> That means that Identity page is to be there and has a link to OpenStack client

I think it is worth to try it, but please keep in mind that some OSC command objects provide a few services for better user experience.

For example: http://docs.openstack.org/developer/python-openstackclient/command-objects/availability-zone.html

And, it should be done in the python-openstackclient repository.

> 1) every page in http://docs.openstack.org/cli-reference/ to have two links '<name of project> in OSC and second one to point to individual client (until it is obsoleted/removed like Keystone)
Optionally there should be third one for such clients as nova-manage/keystone-manage... - perhaps that should be redirect to Admin guide and maintained there?

agree. it should be more automated way than now as possible.

> 2) it is not user friendly that CLI reference guide doesn't have project name but only . There are two aspects of that:
-it is a bit hard for someone to find Nova/Glance/ in current list and it is not straightforward to know every name of project
Maybe in short-term link to https://www.openstack.org/software/project-navigator/ would be nice

For user experience, especially non-developer user, we intentionally don't use "project name" at the official docs. It is, however, time to reconsider its convention.

[Alexandra Settle (alexandra-settle)]

Okay, lots to think about! Thanks for bringing this to the table.

1. Project name instead of service names - in all fairness, this convention pre-dates my involvement in the project. And admittedly, I too found this very confusing when I first started contributing. A move to change this would be a *very* heavy lifting exercise, but I do believe that this is worth a discussion. But I don't think it is up to the 4 of us to make that decision here. I am happy to start a discussion on the docs mailing list if this is all something we could see as a change? Thoughts?

2. I like your proposed solution. As Kato said though, some of the OSC command objects provider a few services for better user experience. But this does point out that we are potentially running ahead too fast to change to the 'openstack' command without realising the consequences, especially for new users.

So, my question to you - is how to you propose we begin these changes? This would be a long term solution, so it will not happen overnight and I can't imagine everyone will be thrilled.

My recommendation is we bring up these issues in the doc mailing list (for the project/service names) and the other issue we bring up in the dev mailing list (CC doc). This needs to be a bigger discussion.

Lana - how about we also have this discussion in the docs meeting? Kostiantyn would you be able to attend our meeting to discuss this with the group? Here is the information: https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Documentation_team_meeting

We will discuss a potential need for a blueprint/spec after there has been a full discussion. I would like to keep this bug open as a reference point.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/409451

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/409451
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=4d16b13157570dee9c666b327d7d0c5abc2bde21
Submitter: Jenkins
Branch: master

commit 4d16b13157570dee9c666b327d7d0c5abc2bde21
Author: KATO Tomoyuki <email address hidden>
Date: Sat Dec 10 23:22:20 2016 +0900

    [cli-ref] add project name with service name

    Change-Id: I9170a7927f05e00d6ee99b7211109f15fe8aad88
    Partial-Bug: #1490484

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/409601

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/409601
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=c5d63ed971f6613084bb7b72de833a5731e2398c
Submitter: Jenkins
Branch: master

commit c5d63ed971f6613084bb7b72de833a5731e2398c
Author: KATO Tomoyuki <email address hidden>
Date: Mon Dec 12 13:26:03 2016 +0900

    [cli-ref] highlight openstack command at index page

    Change-Id: I117512b9bd1ef264945d0151c0ca741410222e55
    Partial-Bug: #1490484

[Alexandra Settle (alexandra-settle)]

Kato-san - what else do we need to do for this bug alone? Is there anything else we could do to fix this?

[Andreas Jaeger (jaegerandi)]

This is fixed IMHO.