settingsLogin | Registersettings

[openstack-dev] [nova][docs] Concerns with docs migration

0 votes

Now that Stephen Finucane is back from enjoying his youth and
gallivanting all over Europe, and we talked about a few things in IRC
this morning on the docs migration for Nova, I wanted to dump my
concerns here for broader consumption.

  1. We know we have to fix a bunch of broken links by adding in redirects
    [1] which sdague started here [2]. However, that apparently didn't catch
    everything, e.g. [3], so I'm concerned we're missing other broken links.
    Is there a way to find out?

  2. The bottom change in the docs migration series for Nova is a massive
    refactor of the layout of the Nova devref [4]. That's something I don't
    want to do in Pike for two reasons:

a) It's a huge change and we simply don't have the time to invest in
properly assessing and reviewing it before Pike RC1.

b) I think that if we're going to refactor the Nova devref home page to
be a certain format, then we should really consider doing the same thing
in the other projects, because today they are all different formats
[5][6][7]. This is likely a cross-project discussion for the Queens PTG
to determine if the home page for the projects should look similar. It
seems they should given the uniformity that the Foundation has been
working toward lately.

  1. The patch for the import of the admin guide [8] is missing some CLI
    specific pages which are pretty useful given they aren't documented
    anywhere else, like the forced_host part of the compute API [9].
    Basically anything that's cli-nova-* in the admin guide should be in the
    Nova docs. It's also missing the compute-flavors page [10] which is
    pretty important for using OpenStack at all.

  2. Similar to #3, but we don't have a patch yet for importing the user
    guide and there are several docs in the user guide that are Nova
    specific so I'd like to make sure we include those, like [11][12].

[1]
http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html
[2] https://review.openstack.org/#/c/489650/
[3] https://review.openstack.org/#/c/489641/
[4] https://review.openstack.org/#/c/478485/
[5] https://docs.openstack.org/cinder/latest/
[6] https://docs.openstack.org/glance/latest/
[7] https://docs.openstack.org/neutron/latest/
[8] https://review.openstack.org/#/c/477497/
[9]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-guide/source/cli-nova-specify-host.rst
[10]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-guide/source/compute-flavors.rst
[11]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-launch-instances.rst
[12]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-delete-an-instance.rst

--

Thanks,

Matt


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
asked Aug 3, 2017 in openstack-dev by mriedemos_at_gmail.c (15,720 points)   2 4 7

26 Responses

0 votes

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
Now that Stephen Finucane is back from enjoying his youth and
gallivanting all over Europe, and we talked about a few things in IRC
this morning on the docs migration for Nova, I wanted to dump my
concerns here for broader consumption.

  1. We know we have to fix a bunch of broken links by adding in redirects
    [1] which sdague started here [2]. However, that apparently didn't catch
    everything, e.g. [3], so I'm concerned we're missing other broken links.
    Is there a way to find out?

We knew this was going to be an issue, but I wasn't aware of any way to fix
this. The solution looks good though - nice work.

Unfortunately I can't think of any cleverer way to identify these broken links
than manual inspection. I'll do this again for all the patches I've authored
and try to do them for any others I encounter.

  1. The bottom change in the docs migration series for Nova is a massive
    refactor of the layout of the Nova devref [4]. That's something I don't
    want to do in Pike for two reasons:

a) It's a huge change and we simply don't have the time to invest in
properly assessing and reviewing it before Pike RC1.

b) I think that if we're going to refactor the Nova devref home page to
be a certain format, then we should really consider doing the same thing
in the other projects, because today they are all different formats
[5][6][7]. This is likely a cross-project discussion for the Queens PTG
to determine if the home page for the projects should look similar. It
seems they should given the uniformity that the Foundation has been
working toward lately.

This is fair. I've been working on this with asettle and I personally agree
with a lot of the changes/design decisions made there. However, I understand
the time constraints so we can surely split this out. I'll work with asettle on
this too.

  1. The patch for the import of the admin guide [8] is missing some CLI
    specific pages which are pretty useful given they aren't documented
    anywhere else, like the forced_host part of the compute API [9].
    Basically anything that's cli-nova-* in the admin guide should be in the
    Nova docs. It's also missing the compute-flavors page [10] which is
    pretty important for using OpenStack at all.

This is a tricky one. Based on previous discussions with dhellmann, the plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx' commands
(i.e. commands using python-novaclient or python-openstackclient) in favour of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with it
(who really uses curl?). In any case though, this would surely be a big rewrite
and, per your concerns in #2 above, doesn't sound like something we should be
doing in Pike. I guess a basic import is the way to go for now. I'll take care
of this.

  1. Similar to #3, but we don't have a patch yet for importing the user
    guide and there are several docs in the user guide that are Nova
    specific so I'd like to make sure we include those, like [11][12].

As above.

Stephen

[1]
http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html
[2] https://review.openstack.org/#/c/489650/
[3] https://review.openstack.org/#/c/489641/
[4] https://review.openstack.org/#/c/478485/
[5] https://docs.openstack.org/cinder/latest/
[6] https://docs.openstack.org/glance/latest/
[7] https://docs.openstack.org/neutron/latest/
[8] https://review.openstack.org/#/c/477497/
[9]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
ide/source/cli-nova-specify-host.rst
[10]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
ide/source/compute-flavors.rst
[11]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
de/source/cli-launch-instances.rst
[12]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
de/source/cli-delete-an-instance.rst


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Stephen_Finucane (1,620 points)   2
0 votes

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
Now that Stephen Finucane is back from enjoying his youth and
gallivanting all over Europe, and we talked about a few things in IRC
this morning on the docs migration for Nova, I wanted to dump my
concerns here for broader consumption.

  1. We know we have to fix a bunch of broken links by adding in redirects
    [1] which sdague started here [2]. However, that apparently didn't catch
    everything, e.g. [3], so I'm concerned we're missing other broken links.
    Is there a way to find out?

Manual inspection is probably the easiest way to go.

  1. The bottom change in the docs migration series for Nova is a massive
    refactor of the layout of the Nova devref [4]. That's something I don't
    want to do in Pike for two reasons:

a) It's a huge change and we simply don't have the time to invest in
properly assessing and reviewing it before Pike RC1.

b) I think that if we're going to refactor the Nova devref home page to
be a certain format, then we should really consider doing the same thing
in the other projects, because today they are all different formats
[5][6][7]. This is likely a cross-project discussion for the Queens PTG
to determine if the home page for the projects should look similar. It
seems they should given the uniformity that the Foundation has been
working toward lately.

  1. The patch for the import of the admin guide [8] is missing some CLI
    specific pages which are pretty useful given they aren't documented
    anywhere else, like the forced_host part of the compute API [9].
    Basically anything that's cli-nova-* in the admin guide should be in the
    Nova docs. It's also missing the compute-flavors page [10] which is
    pretty important for using OpenStack at all.

  2. Similar to #3, but we don't have a patch yet for importing the user
    guide and there are several docs in the user guide that are Nova
    specific so I'd like to make sure we include those, like [11][12].

[1]
http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html
[2] https://review.openstack.org/#/c/489650/
[3] https://review.openstack.org/#/c/489641/
[4] https://review.openstack.org/#/c/478485/
[5] https://docs.openstack.org/cinder/latest/
[6] https://docs.openstack.org/glance/latest/
[7] https://docs.openstack.org/neutron/latest/
[8] https://review.openstack.org/#/c/477497/
[9]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
ide/source/cli-nova-specify-host.rst
[10]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
ide/source/compute-flavors.rst
[11]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
de/source/cli-launch-instances.rst
[12]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
de/source/cli-delete-an-instance.rst


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Stephen_Finucane (1,620 points)   2
0 votes

On 08/02/2017 09:22 AM, Stephen Finucane wrote:
On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:

  1. The patch for the import of the admin guide [8] is missing some CLI
    specific pages which are pretty useful given they aren't documented
    anywhere else, like the forced_host part of the compute API [9].
    Basically anything that's cli-nova-* in the admin guide should be in the
    Nova docs. It's also missing the compute-flavors page [10] which is
    pretty important for using OpenStack at all.

This is a tricky one. Based on previous discussions with dhellmann, the plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx' commands
(i.e. commands using python-novaclient or python-openstackclient) in favour of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with it
(who really uses curl?)

Are we going to document the python clients elsewhere then? Personally I find
it highly useful to have complete examples of how to do things with
python-novaclient or python-openstackclient.

Given that any users of the raw HTTP API are likely going to be developers,
while users of the CLI tools may not be, it seems more important to give good
examples of using the CLI tools. Any developer should be able to figure out the
underlying HTTP (using the --debug option of the CLI tool if necessary).

Chris


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Chris_Friesen (20,420 points)   3 16 24
0 votes

On Wed, 2 Aug 2017, Stephen Finucane wrote:
Unfortunately I can't think of any cleverer way to identify these broken links
than manual inspection. I'll do this again for all the patches I've authored
and try to do them for any others I encounter.

if there's access available to the web server logs:

Get access to the server logs, grep for 404 response codes, sort by
url, order by count. Anything that has a high number should be
compared with the .htaccess file that Sean created.

This is a tricky one. Based on previous discussions with dhellmann, the plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx' commands
(i.e. commands using python-novaclient or python-openstackclient) in favour of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with it
(who really uses curl?). In any case though, this would surely be a big rewrite
and, per your concerns in #2 above, doesn't sound like something we should be
doing in Pike. I guess a basic import is the way to go for now. I'll take care
of this.

As much as I think using the raw HTTP is an important learning
tool, using curl in the docs will make the docs very hard to
comprehend.

--
Chris Dent (⊙_⊙') https://anticdent.org/
freenode: cdent tw: @anticdent__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

responded Aug 2, 2017 by cdent_plus_os_at_ant (12,800 points)   2 2 4
0 votes

On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:
On 08/02/2017 09:22 AM, Stephen Finucane wrote:

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:

  1. The patch for the import of the admin guide [8] is missing some CLI
    specific pages which are pretty useful given they aren't documented
    anywhere else, like the forced_host part of the compute API [9].
    Basically anything that's cli-nova-* in the admin guide should be in the
    Nova docs. It's also missing the compute-flavors page [10] which is
    pretty important for using OpenStack at all.

This is a tricky one. Based on previous discussions with dhellmann, the
plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx'
commands
(i.e. commands using python-novaclient or python-openstackclient) in favour
of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with
it
(who really uses curl?)

Are we going to document the python clients elsewhere then?

I think the docs would go into the respective python clients docs?

Personally I find it highly useful to have complete examples of how to do
things with python-novaclient or python-openstackclient.

I agree. Personally, I'd like to see something like Stripe's API docs [1],
maybe through a not-yet-existant 'sphinx-slate' extension [2], but that seems a
lot of work for very little gain and would need serious maintaining.

Given that any users of the raw HTTP API are likely going to be developers,
while users of the CLI tools may not be, it seems more important to give
good examples of using the CLI tools. Any developer should be able to figure
out the underlying HTTP (using the --debug option of the CLI tool if
necessary).

I think the main idea is that the 'python-*client's are not the only game in
town and should not be treated as such. Who these other clients are is a
question I don't personally know the answer to, however.

In any case, this is surely a post-Pike issue, as noted above.

Stephen

[1] https://stripe.com/docs/api
[2] https://github.com/lord/slate


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Stephen_Finucane (1,620 points)   2
0 votes

Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:

On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:

On 08/02/2017 09:22 AM, Stephen Finucane wrote:

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:

  1. The patch for the import of the admin guide [8] is missing some CLI
    specific pages which are pretty useful given they aren't documented
    anywhere else, like the forced_host part of the compute API [9].
    Basically anything that's cli-nova-* in the admin guide should be in the
    Nova docs. It's also missing the compute-flavors page [10] which is
    pretty important for using OpenStack at all.

This is a tricky one. Based on previous discussions with dhellmann, the
plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx'
commands
(i.e. commands using python-novaclient or python-openstackclient) in favour
of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with
it
(who really uses curl?)

Are we going to document the python clients elsewhere then?

I think the docs would go into the respective python clients docs?

Right. I don't remember the details of the curl discussion, but I
think what I was trying to say there was that the "nova" command
line tool installed via python-novaclient should be documented as
part of the openstack/python-novaclient repo rather than openstack/nova.
A CLI reference for nova-manage, which I think is in openstack/nova,
could be documented in openstack/nova.

Basically, put the docs with the code, which is the whole point of this
migration.

Doug


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Doug_Hellmann (87,520 points)   3 4 8
0 votes

Thanks for summarizing the concerns. It is really helpful for all projects!

2017-08-02 23:55 GMT+09:00 Matt Riedemann mriedemos@gmail.com:

Now that Stephen Finucane is back from enjoying his youth and gallivanting
all over Europe, and we talked about a few things in IRC this morning on the
docs migration for Nova, I wanted to dump my concerns here for broader
consumption.

  1. We know we have to fix a bunch of broken links by adding in redirects [1]
    which sdague started here [2]. However, that apparently didn't catch
    everything, e.g. [3], so I'm concerned we're missing other broken links. Is
    there a way to find out?

  2. The bottom change in the docs migration series for Nova is a massive
    refactor of the layout of the Nova devref [4]. That's something I don't want
    to do in Pike for two reasons:

a) It's a huge change and we simply don't have the time to invest in
properly assessing and reviewing it before Pike RC1.

b) I think that if we're going to refactor the Nova devref home page to be a
certain format, then we should really consider doing the same thing in the
other projects, because today they are all different formats [5][6][7]. This
is likely a cross-project discussion for the Queens PTG to determine if the
home page for the projects should look similar. It seems they should given
the uniformity that the Foundation has been working toward lately.

Totally agree for PTG topics. we need some guideline on what the top pages of
individual projects should be and what are expected for top pages of
sub directories.
When the doc-migration started, I chatted on this a bit with asettle.
The top page of each subdirectory (like admin, install and so on) are
expected to link
from a landing page on docs.openstack.org. On the other hand, we also need to
take care of the top page of individual projects. In neutron case, we
basically try to
accommodate all documents in the standard directory structure and keep
the top page as much as simple.
It is really nice to have a consistent guideline on this.

  1. The patch for the import of the admin guide [8] is missing some CLI
    specific pages which are pretty useful given they aren't documented anywhere
    else, like the forced_host part of the compute API [9]. Basically anything
    that's cli-nova-* in the admin guide should be in the Nova docs. It's also
    missing the compute-flavors page [10] which is pretty important for using
    OpenStack at all.

Perhaps what we need are pages which explains how to use and configure
a specific feature using on CLI and/or some. It might be beyond the
scope of cli-nova-*.
I think the end-user and admin guides can be refactored per topic.

  1. Similar to #3, but we don't have a patch yet for importing the user guide
    and there are several docs in the user guide that are Nova specific so I'd
    like to make sure we include those, like [11][12].

[1]
http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html
[2] https://review.openstack.org/#/c/489650/
[3] https://review.openstack.org/#/c/489641/
[4] https://review.openstack.org/#/c/478485/
[5] https://docs.openstack.org/cinder/latest/
[6] https://docs.openstack.org/glance/latest/
[7] https://docs.openstack.org/neutron/latest/
[8] https://review.openstack.org/#/c/477497/
[9]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-guide/source/cli-nova-specify-host.rst
[10]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-guide/source/compute-flavors.rst
[11]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-launch-instances.rst
[12]
https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-delete-an-instance.rst

--

Thanks,

Matt


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Akihiro_Motoki (8,520 points)   2 3 4
0 votes

2017-08-03 0:52 GMT+09:00 Doug Hellmann doug@doughellmann.com:

Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:

On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:

On 08/02/2017 09:22 AM, Stephen Finucane wrote:

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:

  1. The patch for the import of the admin guide [8] is missing some CLI
    specific pages which are pretty useful given they aren't documented
    anywhere else, like the forced_host part of the compute API [9].
    Basically anything that's cli-nova-* in the admin guide should be in the
    Nova docs. It's also missing the compute-flavors page [10] which is
    pretty important for using OpenStack at all.

This is a tricky one. Based on previous discussions with dhellmann, the
plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx'
commands
(i.e. commands using python-novaclient or python-openstackclient) in favour
of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with
it
(who really uses curl?)

Are we going to document the python clients elsewhere then?

I think the docs would go into the respective python clients docs?

Right. I don't remember the details of the curl discussion, but I
think what I was trying to say there was that the "nova" command
line tool installed via python-novaclient should be documented as
part of the openstack/python-novaclient repo rather than openstack/nova.
A CLI reference for nova-manage, which I think is in openstack/nova,
could be documented in openstack/nova.

Basically, put the docs with the code, which is the whole point of this
migration.

It is true for CLI reference.
The gray zone is CLI stuffs in the admin guide and/or end-user guide.
I think this is the point Matt raised.
cli-nova-* stuffs in the admin guide was per topic like launching instance,
migrating instances and so on. It is actually beyond the CLI reference to me.
It is about how to use specific features of nova.
IMHO this kind of stuffs can be covered by the admin guide or user guide,
so it fits into openstack/nova (or other server projects).

Akihiro

Doug


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Akihiro_Motoki (8,520 points)   2 3 4
0 votes

Excerpts from Akihiro Motoki's message of 2017-08-03 01:02:59 +0900:

2017-08-03 0:52 GMT+09:00 Doug Hellmann doug@doughellmann.com:

Excerpts from Stephen Finucane's message of 2017-08-02 16:35:23 +0100:

On Wed, 2017-08-02 at 09:28 -0600, Chris Friesen wrote:

On 08/02/2017 09:22 AM, Stephen Finucane wrote:

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:

  1. The patch for the import of the admin guide [8] is missing some CLI
    specific pages which are pretty useful given they aren't documented
    anywhere else, like the forced_host part of the compute API [9].
    Basically anything that's cli-nova-* in the admin guide should be in the
    Nova docs. It's also missing the compute-flavors page [10] which is
    pretty important for using OpenStack at all.

This is a tricky one. Based on previous discussions with dhellmann, the
plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx'
commands
(i.e. commands using python-novaclient or python-openstackclient) in favour
of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with
it
(who really uses curl?)

Are we going to document the python clients elsewhere then?

I think the docs would go into the respective python clients docs?

Right. I don't remember the details of the curl discussion, but I
think what I was trying to say there was that the "nova" command
line tool installed via python-novaclient should be documented as
part of the openstack/python-novaclient repo rather than openstack/nova.
A CLI reference for nova-manage, which I think is in openstack/nova,
could be documented in openstack/nova.

Basically, put the docs with the code, which is the whole point of this
migration.

It is true for CLI reference.
The gray zone is CLI stuffs in the admin guide and/or end-user guide.
I think this is the point Matt raised.
cli-nova-* stuffs in the admin guide was per topic like launching instance,
migrating instances and so on. It is actually beyond the CLI reference to me.
It is about how to use specific features of nova.
IMHO this kind of stuffs can be covered by the admin guide or user guide,
so it fits into openstack/nova (or other server projects).

Yeah, I don't know.

My gut response is to say that if the example uses nova-manage or
one of the nova service executables, then that makes sense to leave
in the nova tree, but otherwise it should go into either the
python-novaclient or python-openstackclient repositories (depending
on which command line tool is used in the example).

On the other hand, I can see that being somewhat confusing for
someone who lands at the nova docs and can't find instructions for
how to use it. Maybe less confusing, though, than if I am not
running nova but am trying to use a nova deployed by someone else
and I start from the python-novaclient or python-openstackclient
docs because I installed one of those in order to talk to nova.

I thought "put the docs with the code" would be a simple enough
rule that we wouldn't have to think too hard about where to put
individual example files, which would speed up the migration.

Doug

Akihiro

Doug


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Doug_Hellmann (87,520 points)   3 4 8
0 votes

On Wed, Aug 2, 2017, at 07:55 AM, Matt Riedemann wrote:
Now that Stephen Finucane is back from enjoying his youth and
gallivanting all over Europe, and we talked about a few things in IRC
this morning on the docs migration for Nova, I wanted to dump my
concerns here for broader consumption.

  1. We know we have to fix a bunch of broken links by adding in redirects
    [1] which sdague started here [2]. However, that apparently didn't catch
    everything, e.g. [3], so I'm concerned we're missing other broken links.
    Is there a way to find out?

The infra team can generate lists of 404 urls fairly easily on the docs
server. This won't show you everything but will show you what urls
people are finding/using that 404.

snip

Clark


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Clark_Boylan (8,800 points)   1 2 4
...