[ptls][all][tc][docs] Documentation migration spec

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
16 messages Options
Reply | Threaded
Open this post in threaded view
|

[ptls][all][tc][docs] Documentation migration spec

Alexandra Settle-2

Hi everyone,

 

Doug and I have written up a spec following on from the conversation [0] that we had regarding the documentation publishing future.

 

Please take the time out of your day to review the spec as this affects *everyone*.

 

See: https://review.openstack.org/#/c/472275/

 

I will be PTO from the 9th – 19th of June. If you have any pressing concerns, please email me and I will get back to you as soon as I can, or, email Doug Hellmann and hopefully he will be able to assist you.

 

Thanks,

 

Alex

 

[0] http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html


__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [keystone][glance][nova][neutron][horizon][cinder][osc][swift][manila][telemetry][heat][ptls][all][tc][docs] Documentation migration spec

Doug Hellmann-2
I added subject tags for the projects most affected by this change. It
would be good to have the PTLs or liaisons from those teams review the
spec so there are no surprises when we start moving files around.

Excerpts from Alexandra Settle's message of 2017-06-08 15:17:34 +0000:

> Hi everyone,
>
> Doug and I have written up a spec following on from the conversation [0] that we had regarding the documentation publishing future.
>
> Please take the time out of your day to review the spec as this affects *everyone*.
>
> See: https://review.openstack.org/#/c/472275/
>
> I will be PTO from the 9th – 19th of June. If you have any pressing concerns, please email me and I will get back to you as soon as I can, or, email Doug Hellmann and hopefully he will be able to assist you.
>
> Thanks,
>
> Alex
>
> [0] http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [keystone][glance][nova][neutron][horizon][cinder][osc][swift][manila][telemetry][heat][ptls][all][tc][docs] Documentation migration spec

Doug Hellmann-2
Excerpts from Doug Hellmann's message of 2017-06-12 11:43:25 -0400:
> I added subject tags for the projects most affected by this change. It
> would be good to have the PTLs or liaisons from those teams review the
> spec so there are no surprises when we start moving files around.

I have set up patches for oslo.config, glance, glance client,
python-openstackclient, and horizon for folks to use as examples
[1]. I've also updated the tracking etherpad [2] with some more
detailed directions.

I hope the examples will answer any remaining questions about the
plan and PTLs will sign-off on the spec so we can move forward in
earnest next week.

Doug

[1] https://review.openstack.org/#/q/topic:doc-migration
[2] https://etherpad.openstack.org/p/doc-migration-tracking

>
> Excerpts from Alexandra Settle's message of 2017-06-08 15:17:34 +0000:
> > Hi everyone,
> >
> > Doug and I have written up a spec following on from the conversation [0] that we had regarding the documentation publishing future.
> >
> > Please take the time out of your day to review the spec as this affects *everyone*.
> >
> > See: https://review.openstack.org/#/c/472275/
> >
> > I will be PTO from the 9th – 19th of June. If you have any pressing concerns, please email me and I will get back to you as soon as I can, or, email Doug Hellmann and hopefully he will be able to assist you.
> >
> > Thanks,
> >
> > Alex
> >
> > [0] http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html
>

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [keystone][glance][nova][neutron][horizon][cinder][osc][swift][manila][telemetry][heat][ptls][all][tc][docs] Documentation migration spec

Alexandra Settle-2
In reply to this post by Alexandra Settle-2
Hi everyone,

Doug has been working hard in my absence to answer everyone’s questions and concerns on the migration spec. Thanks to all that have taken the time to review.

Due to our limited time frame, we are now looking for the PTLs to provide their respective +1’s (or -1’s) on the patch.

Cheers,

Alex

On 6/15/17, 11:26 PM, "Doug Hellmann" <[hidden email]> wrote:

    Excerpts from Doug Hellmann's message of 2017-06-12 11:43:25 -0400:
    > I added subject tags for the projects most affected by this change. It
    > would be good to have the PTLs or liaisons from those teams review the
    > spec so there are no surprises when we start moving files around.
   
    I have set up patches for oslo.config, glance, glance client,
    python-openstackclient, and horizon for folks to use as examples
    [1]. I've also updated the tracking etherpad [2] with some more
    detailed directions.
   
    I hope the examples will answer any remaining questions about the
    plan and PTLs will sign-off on the spec so we can move forward in
    earnest next week.
   
    Doug
   
    [1] https://review.openstack.org/#/q/topic:doc-migration
    [2] https://etherpad.openstack.org/p/doc-migration-tracking
   
    >
    > Excerpts from Alexandra Settle's message of 2017-06-08 15:17:34 +0000:
    > > Hi everyone,
    > >
    > > Doug and I have written up a spec following on from the conversation [0] that we had regarding the documentation publishing future.
    > >
    > > Please take the time out of your day to review the spec as this affects *everyone*.
    > >
    > > See: https://review.openstack.org/#/c/472275/
    > >
    > > I will be PTO from the 9th – 19th of June. If you have any pressing concerns, please email me and I will get back to you as soon as I can, or, email Doug Hellmann and hopefully he will be able to assist you.
    > >
    > > Thanks,
    > >
    > > Alex
    > >
    > > [0] http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html
    >
   
    __________________________________________________________________________
    OpenStack Development Mailing List (not for usage questions)
    Unsubscribe: [hidden email]?subject:unsubscribe
    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
   

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

Doug Hellmann-2
In reply to this post by Alexandra Settle-2
Excerpts from Alexandra Settle's message of 2017-06-08 15:17:34 +0000:

> Hi everyone,
>
> Doug and I have written up a spec following on from the conversation [0] that we had regarding the documentation publishing future.
>
> Please take the time out of your day to review the spec as this affects *everyone*.
>
> See: https://review.openstack.org/#/c/472275/
>
> I will be PTO from the 9th – 19th of June. If you have any pressing concerns, please email me and I will get back to you as soon as I can, or, email Doug Hellmann and hopefully he will be able to assist you.
>
> Thanks,
>
> Alex
>
> [0] http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html

Andreas pointed out that the new documentation job will behave a
little differently from the old setup, and thought I should mention
it so that people aren't surprised.

The new job is configured to update the docs for all repos every
time a patch is merged, not just when we tag releases. The server
projects have been working that way, but this is different for some
of the libraries, especially the clients.

I will be going back and adding a step to build the docs when we
tag releases after the move actually starts, so that we can link
to docs for specific versions of projects. That change will be
transparent to everyone else, so I have it on the list for after
the migration is under way.

Doug

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

[ptls][all][tc][docs] Documentation migration spec

Alexandra Settle-2
In reply to this post by Alexandra Settle-2

Hi everyone,

 

This morning (afternoon) the specification for the documentation migration was merged. Thanks to all that took time to review :)

 

You can now view here in all its glory: https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html

 

If you have any questions, feel free to shoot them to me or Doug :)

 

Let’s begin!

 

Alex


__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

Renat Akhmerov-2
In reply to this post by Doug Hellmann-2
I can say for Mistral . We only planned to add Mistral docs to the central repo but didn’t do it yet. So, as far as I understand, we don’t need to move anything. We’ll review the spec and adjust the folder structure according to the proposed.

Thanks

Renat Akhmerov
@Nokia

23 июня 2017 г., 3:32 +0700, Doug Hellmann <[hidden email]>, писал:
Excerpts from Alexandra Settle's message of 2017-06-08 15:17:34 +0000:
Hi everyone,

Doug and I have written up a spec following on from the conversation [0] that we had regarding the documentation publishing future.

Please take the time out of your day to review the spec as this affects *everyone*.

See: https://review.openstack.org/#/c/472275/

I will be PTO from the 9th – 19th of June. If you have any pressing concerns, please email me and I will get back to you as soon as I can, or, email Doug Hellmann and hopefully he will be able to assist you.

Thanks,

Alex

[0] http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html

Andreas pointed out that the new documentation job will behave a
little differently from the old setup, and thought I should mention
it so that people aren't surprised.

The new job is configured to update the docs for all repos every
time a patch is merged, not just when we tag releases. The server
projects have been working that way, but this is different for some
of the libraries, especially the clients.

I will be going back and adding a step to build the docs when we
tag releases after the move actually starts, so that we can link
to docs for specific versions of projects. That change will be
transparent to everyone else, so I have it on the list for after
the migration is under way.

Doug

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

Doug Hellmann-2

On Jun 23, 2017, at 8:57 AM, Renat Akhmerov <[hidden email]> wrote:

I can say for Mistral . We only planned to add Mistral docs to the central repo but didn’t do it yet. So, as far as I understand, we don’t need to move anything. We’ll review the spec and adjust the folder structure according to the proposed.

Please do review the steps in the spec. Not all of them are about moving content. There are steps for setting up the new build job so that the content will be published to the new URLs as well.

Doug


Thanks

Renat Akhmerov
@Nokia

23 июня 2017 г., 3:32 +0700, Doug Hellmann <[hidden email]>, писал:
Excerpts from Alexandra Settle's message of 2017-06-08 15:17:34 +0000:
Hi everyone,

Doug and I have written up a spec following on from the conversation [0] that we had regarding the documentation publishing future.

Please take the time out of your day to review the spec as this affects *everyone*.

See: https://review.openstack.org/#/c/472275/

I will be PTO from the 9th – 19th of June. If you have any pressing concerns, please email me and I will get back to you as soon as I can, or, email Doug Hellmann and hopefully he will be able to assist you.

Thanks,

Alex

[0] http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html

Andreas pointed out that the new documentation job will behave a
little differently from the old setup, and thought I should mention
it so that people aren't surprised.

The new job is configured to update the docs for all repos every
time a patch is merged, not just when we tag releases. The server
projects have been working that way, but this is different for some
of the libraries, especially the clients.

I will be going back and adding a step to build the docs when we
tag releases after the move actually starts, so that we can link
to docs for specific versions of projects. That change will be
transparent to everyone else, so I have it on the list for after
the migration is under way.

Doug

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

j.klare@cloudbau.de
Hi Doug,

first of all sorry for the late response. I am the current PTL of the openstack-chef project and read the spec a while ago, but did not really connect it to our project. To be honest, i am not really sure what we would move and how to do it. Currently we have some wiki pages, but most of them are pretty old and completely outdated since we stopped caring for them after we dropped to only a few contributors and moved our focus to maintaining the project code itself.

Currently we own and maintain 12 service and ops cookbook repositories:

cookbook-openstack-block-storage
cookbook-openstack-common
cookbook-openstack-compute
cookbook-openstack-dashboard
cookbook-openstack-identity
cookbook-openstack-image
cookbook-openstack-integration-test
cookbook-openstack-network
cookbook-openstack-ops-database
cookbook-openstack-ops-messaging
cookbook-openstack-orchestration
cookbook-openstack-telemetry

one (not very often used) specs repository:

openstack-chef-specs

 and one repo to integrate them all:

openstack-chef-repo

All of these repos have some READMEs that contain some of the documentation needed to use these. The documentation on how to use the openstack-chef project as a combination of all these cookbooks, is located under https://github.com/openstack/openstack-chef-repo/tree/master/doc (which might already be close to the right space ?). Looking through the openstack-manuals repo, i did not find any documentation specific for our projects, so i think we do not need to export/import any of it. In my opinion the easiest way to follow the proposed change of us would be to just move the stuff we have under the ‘openstack-chef-repo’ mentioned above and add some more files to follow the ‘minimal layout’. If you agree on this, i can try to push a patch for it next week and add you as a reviewer?

Cheers,
Jan


On 23. June 2017 at 16:16:58, Doug Hellmann ([hidden email]) wrote:


On Jun 23, 2017, at 8:57 AM, Renat Akhmerov <[hidden email]> wrote:

I can say for Mistral . We only planned to add Mistral docs to the central repo but didn’t do it yet. So, as far as I understand, we don’t need to move anything. We’ll review the spec and adjust the folder structure according to the proposed.

Please do review the steps in the spec. Not all of them are about moving content. There are steps for setting up the new build job so that the content will be published to the new URLs as well.

Doug


Thanks

Renat Akhmerov
@Nokia

23 июня 2017 г., 3:32 +0700, Doug Hellmann <[hidden email]>, писал:
Excerpts from Alexandra Settle's message of 2017-06-08 15:17:34 +0000:
Hi everyone,

Doug and I have written up a spec following on from the conversation [0] that we had regarding the documentation publishing future.

Please take the time out of your day to review the spec as this affects *everyone*.

See: https://review.openstack.org/#/c/472275/

I will be PTO from the 9th – 19th of June. If you have any pressing concerns, please email me and I will get back to you as soon as I can, or, email Doug Hellmann and hopefully he will be able to assist you.

Thanks,

Alex

[0] http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html

Andreas pointed out that the new documentation job will behave a
little differently from the old setup, and thought I should mention
it so that people aren't surprised.

The new job is configured to update the docs for all repos every
time a patch is merged, not just when we tag releases. The server
projects have been working that way, but this is different for some
of the libraries, especially the clients.

I will be going back and adding a step to build the docs when we
tag releases after the move actually starts, so that we can link
to docs for specific versions of projects. That change will be
transparent to everyone else, so I have it on the list for after
the migration is under way.

Doug

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

Doug Hellmann-2

On Jun 23, 2017, at 12:10 PM, [hidden email] wrote:

Hi Doug,

first of all sorry for the late response. I am the current PTL of the openstack-chef project and read the spec a while ago, but did not really connect it to our project. To be honest, i am not really sure what we would move and how to do it. Currently we have some wiki pages, but most of them are pretty old and completely outdated since we stopped caring for them after we dropped to only a few contributors and moved our focus to maintaining the project code itself.

Currently we own and maintain 12 service and ops cookbook repositories:

cookbook-openstack-block-storage
cookbook-openstack-common
cookbook-openstack-compute
cookbook-openstack-dashboard
cookbook-openstack-identity
cookbook-openstack-image
cookbook-openstack-integration-test
cookbook-openstack-network
cookbook-openstack-ops-database
cookbook-openstack-ops-messaging
cookbook-openstack-orchestration
cookbook-openstack-telemetry

one (not very often used) specs repository:

openstack-chef-specs

 and one repo to integrate them all:

openstack-chef-repo

All of these repos have some READMEs that contain some of the documentation needed to use these. The documentation on how to use the openstack-chef project as a combination of all these cookbooks, is located under https://github.com/openstack/openstack-chef-repo/tree/master/doc (which might already be close to the right space ?). Looking through the openstack-manuals repo, i did not find any documentation specific for our projects, so i think we do not need to export/import any of it. In my opinion the easiest way to follow the proposed change of us would be to just move the stuff we have under the ‘openstack-chef-repo’ mentioned above and add some more files to follow the ‘minimal layout’. If you agree on this, i can try to push a patch for it next week and add you as a reviewer?

Yes, it sounds like you only need to move things you already have around into the new structure. You don’t need to create empty directories or pages for content that doesn’t apply, so if you don’t have any configuration guide instructions for example then you don’t need to create the configuration/ directory.

If you add me as a reviewer, I’ll help make sure you have it organized as expected. And if you use the doc-migration tag the other folks working on the migration will review the patch, too.

Doug


Cheers,
Jan


On 23. June 2017 at 16:16:58, Doug Hellmann ([hidden email]) wrote:


On Jun 23, 2017, at 8:57 AM, Renat Akhmerov <[hidden email]> wrote:

I can say for Mistral . We only planned to add Mistral docs to the central repo but didn’t do it yet. So, as far as I understand, we don’t need to move anything. We’ll review the spec and adjust the folder structure according to the proposed.

Please do review the steps in the spec. Not all of them are about moving content. There are steps for setting up the new build job so that the content will be published to the new URLs as well.

Doug


Thanks

Renat Akhmerov
@Nokia

23 июня 2017 г., 3:32 +0700, Doug Hellmann <[hidden email]>, писал:
Excerpts from Alexandra Settle's message of 2017-06-08 15:17:34 +0000:
Hi everyone,

Doug and I have written up a spec following on from the conversation [0] that we had regarding the documentation publishing future.

Please take the time out of your day to review the spec as this affects *everyone*.

See: https://review.openstack.org/#/c/472275/

I will be PTO from the 9th – 19th of June. If you have any pressing concerns, please email me and I will get back to you as soon as I can, or, email Doug Hellmann and hopefully he will be able to assist you.

Thanks,

Alex

[0] http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html

Andreas pointed out that the new documentation job will behave a
little differently from the old setup, and thought I should mention
it so that people aren't surprised.

The new job is configured to update the docs for all repos every
time a patch is merged, not just when we tag releases. The server
projects have been working that way, but this is different for some
of the libraries, especially the clients.

I will be going back and adding a step to build the docs when we
tag releases after the move actually starts, so that we can link
to docs for specific versions of projects. That change will be
transparent to everyone else, so I have it on the list for after
the migration is under way.

Doug

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

Doug Hellmann-2
In reply to this post by Alexandra Settle-2
Excerpts from Alexandra Settle's message of 2017-06-08 15:17:34 +0000:

> Hi everyone,
>
> Doug and I have written up a spec following on from the conversation [0] that we had regarding the documentation publishing future.
>
> Please take the time out of your day to review the spec as this affects *everyone*.
>
> See: https://review.openstack.org/#/c/472275/
>
> I will be PTO from the 9th – 19th of June. If you have any pressing concerns, please email me and I will get back to you as soon as I can, or, email Doug Hellmann and hopefully he will be able to assist you.
>
> Thanks,
>
> Alex
>
> [0] http://lists.openstack.org/pipermail/openstack-dev/2017-May/117162.html

Someone left a few questions about the directions on the tracking
etherpad [1]. I tried to answer them in place, but next time *please*
post to the mailing list. I have no idea how long those questions were
there before I noticed them, and given how little time we have to do the
work I want to make sure everyone understands as soon as possible.

Doug

[1] https://etherpad.openstack.org/p/doc-migration-tracking

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

Jeremy Stanley
In reply to this post by Doug Hellmann-2
On 2017-06-22 16:27:34 -0400 (-0400), Doug Hellmann wrote:
[...]
> The new job is configured to update the docs for all repos every
> time a patch is merged, not just when we tag releases. The server
> projects have been working that way, but this is different for some
> of the libraries, especially the clients.
[...]

I think the past concern had been that since the default document
presented was the latest one built from the master branch tip rather
than a redirect to the documentation for the latest release, readers
might get confused when seeing options or behaviors documented which
didn't match the software they had downloaded.
--
Jeremy Stanley

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

signature.asc (968 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

Doug Hellmann-2
Excerpts from Jeremy Stanley's message of 2017-06-27 17:55:57 +0000:

> On 2017-06-22 16:27:34 -0400 (-0400), Doug Hellmann wrote:
> [...]
> > The new job is configured to update the docs for all repos every
> > time a patch is merged, not just when we tag releases. The server
> > projects have been working that way, but this is different for some
> > of the libraries, especially the clients.
> [...]
>
> I think the past concern had been that since the default document
> presented was the latest one built from the master branch tip rather
> than a redirect to the documentation for the latest release, readers
> might get confused when seeing options or behaviors documented which
> didn't match the software they had downloaded.

That makes sense. The openstackdocstheme makes it easy to link to
specific versions of documentation, so we should be able to address this
concern that way. We will also have series-specific landing pages
linking directly to the appropriate guides.

Doug

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

Andreas Jaeger
In reply to this post by Alexandra Settle-2
For those migrating from oslosphinx to openstackdocstheme, I strongly
advise to follow the docs for openstackdocstheme 1.11 on how to set it up:

https://docs.openstack.org/openstackdocstheme/latest/

Andreas
--
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Felix Imendörffer, Jane Smithard, Graham Norton,
       HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

Doug Hellmann-2
In reply to this post by Alexandra Settle-2
Excerpts from Alexandra Settle's message of 2017-06-23 12:09:41 +0000:

> Hi everyone,
>
> This morning (afternoon) the specification for the documentation migration was merged. Thanks to all that took time to review :)
>
> You can now view here in all its glory: https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html
>
> If you have any questions, feel free to shoot them to me or Doug :)
>
> Let’s begin!
>
> Alex

Based on some work Sean did with the nova API reference project, I've
set up a burndown chart to track our progress. It updates hourly.

https://doughellmann.com/doc-migration/

Doug

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Reply | Threaded
Open this post in threaded view
|

Re: [ptls][all][tc][docs] Documentation migration spec

Doug Hellmann-2
In reply to this post by Andreas Jaeger
Excerpts from Andreas Jaeger's message of 2017-06-28 08:45:47 +0200:
> For those migrating from oslosphinx to openstackdocstheme, I strongly
> advise to follow the docs for openstackdocstheme 1.11 on how to set it up:
>
> https://docs.openstack.org/openstackdocstheme/latest/
>
> Andreas

Another work item is moving the automatically generated class
documentation that pbr produces by setting the api_doc_dir value
in the pbr section of setup.cfg.

See https://docs.openstack.org/developer/pbr/user/using.html#pbr
for details and https://review.openstack.org/#/c/478294/2/setup.cfg
for an example.

Doug

__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [hidden email]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev