Re: [openstack-dev] [infra][docs] Why Manila api-ref doc isn't published?

[Anne Gentle]

I want to say there are a couple of in-progress patches to clear this up.

https://review.openstack.org/#/c/495326/
and
https://review.openstack.org/#/c/495887/



On Mon, Sep 4, 2017 at 12:27 PM, Jeremy Stanley  wrote:
> On 2017-09-04 11:10:44 +0800 (+0800), jun zhong wrote:
>> Since we merged many patches [1][2] about api-ref doc in manila 3 weeks
>> ago. But it cannot display in the Manila developer doc [3].   Does anyone
>> have any idea about this? Do we need to do anything else or just waiting
>> for automatic update? Thanks in advance.
>>
>> [1] https://review.openstack.org/#/c/491661/
>> [2] https://review.openstack.org/#/c/492987/
>> [3] 
>> https://developer.openstack.org/api-ref/shared-file-systems/#consistency-groups-since-api-v2-4
>
> The https://developer.openstack.org/api-ref/shared-file-systems/
> page states it was last updated Tue Jul 18 14:50:45 2017, commit
> 6a9b665; however there's also a different
> https://developer.openstack.org/api-ref/shared-file-system/ page
> which was updated more recently, Sat Sep 2 22:20:31 2017, commit
> c9ab5b8. I found this by browsing
> /afs/openstack.org/developer-docs/api-ref/ and saw the two distinct
> directories so am assuming there's a typo somewhere leading to
> content ending up in shared-file-system (singular) rather than the
> expected shared-file-systems (plural).
>
> Skimming http://codesearch.openstack.org/?q=shared-file-system shows
> there's quite a lot of disagreement on which is correct... Manila's
> api-ref-jobs service parameter was adjusted by
> https://review.openstack.org/480719 to match the service_type from
> https://service-types.openstack.org/service-types.json
> (corresponding to when the old URL ceased being updated). The
> {name}-api-guide job-template has baked-in assumptions that the
> publication URL is derived from this service name.
>
> It's unclear to me whether {name}-api-guide in
> openstack-infra/project-config should be adjusted to require a
> separate URL parameter, or whether the api_reference URL in
> openstack/service-types-authority needs adjusting to agree with the
> service_type there. I'm guessing we'd prefer the latter for
> consistency, but in that case we probably also need to add a
> redirect and clean up as many of the references to the old URL as
> possible.
> --
> Jeremy Stanley
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com

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

Re: [openstack-dev] [nova][docs] O search where art thou?

[Anne Gentle]

On Fri, Aug 11, 2017 at 9:26 AM, Doug Hellmann <d...@doughellmann.com> wrote:
> Excerpts from Sean Dague's message of 2017-08-11 09:10:59 -0400:
>> On 08/11/2017 08:50 AM, Anne Gentle | Just Write Click wrote:
>> > Yeah, I need to circle back in the theme work to make sure both search 
>> > scopes are available. My prior attempt had some wonky CSS debugging and I 
>> > needed to separate patches more.
>> >
>> > I'll put up another patch to the theme today to bring in the Sphinx search 
>> > in the sidebar as it was before.
>> >
>> > I'm not sure how to solve the sort problem Sean notes, would like help 
>> > there.
>> > Hope this helps -
>> > Anne
>>
>> If we have the option to use sphinx baked in search, instead of the
>> bounce out to google swift_search that's being installed, it's all
>> solved. The sphinx search builds the search terms into a compiled
>> javascript file on build, and will only link to content in the tree.
>>
>> I think the thing to do is probably enhance openstackdocstheme to have
>> some toggle of "local_search = True" which would get rid of swift_search
>> and just use baked in local search. Then on a per site basic people
>> could turn it on / off, and openstackdocstheme could still be used for
>> sites that want global search.
>>
>> -Sean
>>
>
> We could also limit the global search to one of the top-level pages in
> the openstack-manuals repo and have the theme link to a search page
> there.
>

Mmm, I think it's simpler to keep the global search in the header
as-is across docs, www, ask, and so on. So, keep it in the header and
add an additional search form for within-project. Sound good?

Anne

> Doug
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova][docs] O search where art thou?

[Anne Gentle]

On Fri, Aug 11, 2017 at 8:10 AM, Sean Dague <s...@dague.net> wrote:
> On 08/11/2017 08:50 AM, Anne Gentle | Just Write Click wrote:
>> Yeah, I need to circle back in the theme work to make sure both search 
>> scopes are available. My prior attempt had some wonky CSS debugging and I 
>> needed to separate patches more.
>>
>> I'll put up another patch to the theme today to bring in the Sphinx search 
>> in the sidebar as it was before.
>>
>> I'm not sure how to solve the sort problem Sean notes, would like help there.
>> Hope this helps -
>> Anne
>
> If we have the option to use sphinx baked in search, instead of the
> bounce out to google swift_search that's being installed, it's all
> solved. The sphinx search builds the search terms into a compiled
> javascript file on build, and will only link to content in the tree.
>
> I think the thing to do is probably enhance openstackdocstheme to have
> some toggle of "local_search = True" which would get rid of swift_search
> and just use baked in local search. Then on a per site basic people
> could turn it on / off, and openstackdocstheme could still be used for
> sites that want global search.

The global search will always be available in the header, so my idea
is to add the scoped-to-project's-collection search to the sidebar.
Let me know if that works and I'll get going on it.

Anne

>
> -Sean
>
> --
> Sean Dague
> http://dague.net
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



-- 

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com

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

Re: [openstack-dev] [nova][docs] O search where art thou?

[Anne Gentle | Just Write Click]

Yeah, I need to circle back in the theme work to make sure both search scopes 
are available. My prior attempt had some wonky CSS debugging and I needed to 
separate patches more.

I'll put up another patch to the theme today to bring in the Sphinx search in 
the sidebar as it was before.

I'm not sure how to solve the sort problem Sean notes, would like help there.
Hope this helps - 
Anne

> On Aug 11, 2017, at 7:32 AM, Sean Dague  wrote:
> 
>> On 08/11/2017 08:22 AM, Matt Riedemann wrote:
>> Before the great docs migration, searching for something in the nova
>> devref was restricted to the nova devref:
>> 
>> https://docs.openstack.org/nova/ocata/search.html?q=rbd_keywords=yes=default
>> 
>> 
>> Now searching for something in the nova docs searches docs.o.o, ask.o.o,
>> maybe other places, but it's basically so many unrelated results it's
>> not usable for me:
>> 
>> https://docs.openstack.org/nova/latest/search.html#stq=rbd=1
>> 
>> Is there a way we can just get the content-specific (restricted to
>> whatever is in the nova repo for docs) search results back and if people
>> want more, they go to docs.o.o to search for stuff?
>> 
>> Because when I'm in nova docs looking for rbd stuff, I don't want to
>> sift through forum questions or glance docs or cinder docs, etc.
> 
> Equally problematic, in the rbd search above it returns content from all
> published branches, and seems to be coming back in reverse order. So
> mitaka content is the first link for folks for searching from latest docs.
> 
>-Sean
> 
> -- 
> Sean Dague
> http://dague.net
> 
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

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

[Anne Gentle | Just Write Click]

> On Aug 2, 2017, at 1:37 PM, Sean Dague  wrote:
> 
>> On 08/02/2017 12:28 PM, Clark Boylan wrote:
>>> 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.
> 
> If we could get a weekly report of 404 urls posted somewhere public,
> that would be extremely useful, because the easy ones based on git
> renames are done, and everything else is going to require human
> inspection to figure out what the right landing target is.
> 

Fantastic idea. 

I love how many more ideas we are getting as more brains share them.

>-Sean
> 
> -- 
> Sean Dague
> http://dague.net
> 
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs][neutron] doc-migration status

[Anne Gentle]

On Sat, Jul 22, 2017 at 12:13 PM, Akihiro Motoki  wrote:
> Hi,
>
> I have a question on admin/ document related to the networking guide
> and would like to have advices from the documentation experts.
>
> It seems the check site by Doug expect all project have admin/ page.
> In the case of neutron the situation is a bit special. We have the
> networking guide as admin/ document
> in the neutron repo and it covers not only neutron itself but also
> neutron stadium projects.
> It means the neutron stadium projects sometimes (often?) have no
> admin/ directory in their own repos
> in favor of adding contents to the networking guide in neutron.
>
> Should Individual neutron stadium projects have their own admin guide
> in their repositories,
> or is it better to keep the networking guide which covers all
> networking stuff in a single guide?

It's better to keep the networking guide as close to what it is now as
possible, based on the web stats and prior input on that guide's
popularity.

Could you list all the neutron stadium projects? That might help
answer the next question, because if they require neutron, it seems
like a single networking guide is a good way forward. If my memory
serves, it was vpnaas, fwaas, and lbaas, and a whole lot more.
Reviewing 
https://specs.openstack.org/openstack/neutron-specs/specs/newton/neutron-stadium.html
I see a lot more with varying amounts of docs. My general guideline at
first glance would be, if they require neutron, let's put them in the
networking guide in the neutron repo.

I may not say the same for storage, because that's a different set of
interdependencies and decisions for operators to make. I don't think
cinder ever had a stadium, for example. But, since the "neutron
stadium" was very contributor-specific, let's make sure we're meeting
consumer needs.

> What is the suggested way on the networking guide as the document expert?

Keep working with us with specific scenarios and details and we can
fill in a set of reader needs, hopefully.

Anne

>
> Thanks,
> Akihiro
>
> 2017-07-22 3:26 GMT+09:00 Doug Hellmann :
>> We've made huge progress, and are launching the updated landing
>> pages for docs.openstack.org as I write this. Thanks to all of the
>> contributors who have stepped up to write nearly 1,000 patches to
>> improve the health of our documentation!
>>
>> We still have around 70 URLs we expected to see after the migration
>> was complete but that produce a 404. I know some of the patches to
>> produce those pages are in progress, but please check the list at
>> https://doughellmann.com/doc-migration/ if your team is listed below
>> to ensure that nothing has been missed.
>>
>>   cinder
>>   cloudkitty
>>   congress
>>   designate
>>   heat
>>   ironic
>>   karbor
>>   keystone
>>   magnum
>>   manila
>>   murano
>>   neutron
>>   nova
>>   sahara
>>   senlin
>>   swift
>>   tacker
>>   telementry
>>   tricircle
>>   trove
>>   vitrage
>>   watcher
>>   zaqar
>>   zun
>>
>> Reply here or ping me in #openstack-docs if you have questions or need a
>> hand.
>>
>> Doug
>>
>> ___
>> OpenStack-docs mailing list
>> openstack-d...@lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



-- 

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com

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

Re: [openstack-dev] [docs] [pbr] [ptl] [oslo] Removing pbr's custom 'build_sphinx' setuptools command

[Anne Gentle]

On Mon, Jul 10, 2017 at 1:11 PM, Doug Hellmann  wrote:
> Excerpts from sfinucan's message of 2017-07-10 17:20:37 +0100:
>> On Fri, 2017-07-07 at 15:58 +0100, sfinu...@redhat.com wrote:
>> > tl;dr: pbr's 'build_spinx' derivative is broken again, and we want to just
>> > remove the feature at this point. However, this is going to necessitate 
>> > some
>> > mechanical changes for most projects with docs and this mail serves as a
>> > heads up and request for input before we proceed.
>>
>> [snip]
>>
>> > Here are the features that the plugin provides, along with the current
>> > migration plans:
>>
>> ...
>>
>> > - Automatically sets project name and version using pbr's machinery
>> >
>> >   Try to set this from 'openstackdocstheme'. If this isn't possible, folks
>> >   will need to add some some lines to 'conf.py' like keystoneauth does [7]
>>
>> I've been looking into this particular issue further, and the more I think
>> about it, the less necessary it seems. There are three configuration options
>> currently set by pbr:
>>
>> - project (the project name)
>> - version (the full version, including alpha/beta/rc tags)
>> - release (the short X.Y version)
>>
>> Of these, 'project' is static and should never change, so we don't need to
>> attempt to guess them. Version and release are dynamic but I've noticed we
>> don't actually use them anywhere in openstackdocstheme (the version you see 
>> in
>> the URL is actually an artefact of the build process and nothing to do with
>> Sphinx). The closest thing we _do_ get to including version information is 
>> the
>> commit ID include in header of api-ref build pages [1], which is generated by
>> openstackdocstheme.
>
> It's surprising to me that we don't include the version string anywhere
> on the page. Is that an oversight in the theme, or was it on purpose?

The theme shows "current" - however I noticed while reviewing this
morning the nomenclature is "latest" in the URL, so I will make a
change. Do you suggest "latest -n.n.n" as the string value, or simply
"latest"?

Anne

>
>> Given this fact, I think pbr is a providing a solution in search of problem
>> here, and this feature can in fact go quietly into the night with no further
>> ado.
>>
>> Thoughts?
>> Stephen
>>
>> PS: If we really did want to include a version in the docs in the future, I
>> think we could use information provided by ZUUL. I'm no ZUUL expert, but it
>> seems ZUUL does have commit id info ('ZUUL_REF') and what I hope to be
>> something like what 'git-describe' ('ZUUL_REFNAME'). We could simply pass 
>> these
>> via the '--version' parameter to 'build_sphinx' [3]. Again though, I don't
>> think this is necessary.
>
> Relying on anything outside of the repo won't work for packagers who
> build from source outside of our CI system.
>
>> PPS: I have not responded to the other replies to this mail yet because Red
>> Hat's email servers have decided not to send me replies to my own posts on
>> openstack-dev. I have seen them though and will reply when I figure out how 
>> to
>> get mboxes.
>>
>> [1] https://developer.openstack.org/api-ref/compute/
>> [2] 
>> https://github.com/openstack-infra/zuul/blob/8dda7c1/tools/trigger-job.py#L
>> 54-L60
>> [3] 
>> https://github.com/openstack-infra/project-config/blob/32aff86f/jenkins/scr
>> ipts/run-docs.sh#L20
>>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



-- 

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com

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

Re: [openstack-dev] [docs] [pbr] [ptl] [oslo] Removing pbr's custom 'build_sphinx' setuptools command

[Anne Gentle]

On Mon, Jul 10, 2017 at 12:20 PM,   wrote:
> On Fri, 2017-07-07 at 15:58 +0100, sfinu...@redhat.com wrote:
>> tl;dr: pbr's 'build_spinx' derivative is broken again, and we want to just
>> remove the feature at this point. However, this is going to necessitate some
>> mechanical changes for most projects with docs and this mail serves as a
>> heads up and request for input before we proceed.
>
> [snip]
>
>> Here are the features that the plugin provides, along with the current
>> migration plans:
>
> ...
>
>> - Automatically sets project name and version using pbr's machinery
>>
>>   Try to set this from 'openstackdocstheme'. If this isn't possible, folks
>>   will need to add some some lines to 'conf.py' like keystoneauth does [7]
>
> I've been looking into this particular issue further, and the more I think
> about it, the less necessary it seems. There are three configuration options
> currently set by pbr:
>
> - project (the project name)
> - version (the full version, including alpha/beta/rc tags)
> - release (the short X.Y version)
>
> Of these, 'project' is static and should never change, so we don't need to
> attempt to guess them. Version and release are dynamic but I've noticed we
> don't actually use them anywhere in openstackdocstheme (the version you see in
> the URL is actually an artefact of the build process and nothing to do with
> Sphinx). The closest thing we _do_ get to including version information is the
> commit ID include in header of api-ref build pages [1], which is generated by
> openstackdocstheme.

The 1.12.0 release of openstackdocstheme provides an option to get to
more than the current version of a project's docs. It acquires the
values by querying the most recent five git tags:

https://review.openstack.org/#/c/477639/

Anne

>
> Given this fact, I think pbr is a providing a solution in search of problem
> here, and this feature can in fact go quietly into the night with no further
> ado.
>
> Thoughts?
> Stephen
>
> PS: If we really did want to include a version in the docs in the future, I
> think we could use information provided by ZUUL. I'm no ZUUL expert, but it
> seems ZUUL does have commit id info ('ZUUL_REF') and what I hope to be
> something like what 'git-describe' ('ZUUL_REFNAME'). We could simply pass 
> these
> via the '--version' parameter to 'build_sphinx' [3]. Again though, I don't
> think this is necessary.
>
> PPS: I have not responded to the other replies to this mail yet because Red
> Hat's email servers have decided not to send me replies to my own posts on
> openstack-dev. I have seen them though and will reply when I figure out how to
> get mboxes.
>
> [1] https://developer.openstack.org/api-ref/compute/
> [2] 
> https://github.com/openstack-infra/zuul/blob/8dda7c1/tools/trigger-job.py#L
> 54-L60
> [3] 
> https://github.com/openstack-infra/project-config/blob/32aff86f/jenkins/scr
> ipts/run-docs.sh#L20
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



-- 

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com

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

Re: [openstack-dev] [docs] Retiring clouddocs-maven-plugin

[Anne Gentle | Just Write Click]

Yes! Thank you, nice to lift that up up and away!
 - 
Anne

> On Jun 30, 2017, at 9:30 AM, Alexandra Settle  wrote:
> 
> Sound proposal. +1 
> 
> Thanks Andreas
> 
> On 6/30/17, 2:16 PM, "Andreas Jaeger"  wrote:
> 
>It's IMHO time to retire
>http://git.openstack.org/cgit/openstack/clouddocs-maven-plugin/ - this
>was used to build documents from XML.
> 
>We converted all documents to RST, have released the last version in
>April 2015, and not merged anything since May 2016.
> 
>Current openstack-manuals got fully converted to RST with Mitaka, so we
>have no current branches that need this.
> 
>Thus I propose to retire the repo and will propose patches for it. Once
>those are submitted, I'll reply here with references to them,
> 
>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: openstack-dev-requ...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all][tc] How to deal with confusion around "hosted projects"

[Anne Gentle]

On Thu, Jun 29, 2017 at 8:49 AM, Jimmy McArthur  wrote:
>
>
> Thierry Carrez wrote:
>>
>> The confusion I'm talking about is not the passive-aggressive from
>> people involved in openstack. It's from our prospective new users, who
>> have no idea about our governance, making random searches on Google.
>> It's from people getting hit by marketing message from projects claiming
>> to be official OpenStack projects, while they are not. It's extremely
>> difficult for those to see clearly, especially with all our online
>> presence reinforcing the confusion.
>
> If there is specifically confusion around Google searches, I'd suggest as a
> first step to spend some time working on redirects for dead projects and
> very clearly updating documentation. For all of Google's magic, there are
> some simple and easy rules to help correct bad search data.

This.

Even though I've worked on the docs for years, I don't think we are
improving on this front.

Jimmy, do you know how to put more recent docs (instead of most
established docs) at the top of the search hits? The nature of the
algorithm rewards longevity over recency, and I've never quite learned
how to take care of that.

Are there other specific ideas you have?

>
> Additionally, we just implemented SwifType on OpenStack.org and docs.o.o b/c
> Google deprecated their Site Search product. We have a ton of control over
> that search and can very easily modify search results.

Pretty sure we want to tackle the "Google is my front page to the
Internet" problem first, but this search change is also excellent and
helpful.

Anne

>
> Let me know if I can be of service on any of these fronts.
>
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



-- 

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com

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

Re: [openstack-dev] [OpenStack-docs] [openstack-docs][dev][all] Documentation repo freeze

[Anne Gentle]

On Tue, Jun 20, 2017 at 3:13 AM, Alexandra Settle  wrote:
>
>
> On 6/19/17, 6:19 PM, "Petr Kovar"  wrote:
>
> On Mon, 19 Jun 2017 15:56:35 +
> Alexandra Settle  wrote:
>
> > Hi everyone,
> >
> > As of today - Monday, the 19th of June – please do NOT merge any 
> patches into
> > the openstack-manuals repository that is not related to the topic:
> > “doc-migration”.
> >
> > We are currently in the phase of setting up for our MASSIVE migration 
> and we
> > need to ensure that there will be minimal conflicts.
> >
> > You can find all patches related to that topic here:
> > 
> https://review.openstack.org/#/q/status:open+project:openstack/openstack-manuals+branch:master+topic:doc-migration
> >
> > The only other patches that should be passed is the Zanata translation 
> patches.
> >
> > If there are any concerns or questions, please do not hesitate to 
> contact either
> > myself or Doug Hellmann for further clarification.
>
> Can we still merge into stable branches? As the migration only affects
> content in master, I think there's no need to freeze stable branches.
>
>
> Good question. I would say yes, as we are only porting over everything that 
> is currently in master for now.
>

Yep, that sounds right to me, if we need to change content in a stable
branch, go ahead.

> I would also like to clarify that this only affects the documentation suite, 
> not the tooling.

Yes, speaking of tooling, can anyone review
https://review.openstack.org/#/c/468021/ -- changes to the them?

Thanks -
Anne

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



-- 

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com

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

Re: [openstack-dev] [Openstack-operators] [dev] [doc] Operations Guide future

[Anne Gentle]

I'm okay with option 3.

Since we hadn't heard from anyone yet who can do the work, I thought I'd
describe a super small experiment to try. If you're interested in the
export, run an experiment with Pandoc to convert from RST to Mediawiki.
http://pandoc.org/demos.html

You'll likely still have cleanup but it's a start. Only convert
troubleshooting to start, which gets the most hits: docs.openstack.org/
ops-guide/ops-network-troubleshooting.html
Then see how much you get from Pandoc.

Let us know how it goes, I'm curious!
Anne



On Fri, Jun 2, 2017 at 4:03 AM, Alexandra Settle 
wrote:

> Blair – correct, it was the majority in the room. I just wanted to reach
> out and ensure that operators had a chance to voice opinions and see where
> we were going (
>
> Sounds like option 3 is still the favorable direction. This is going to be
> a really big exercise, lifting the content out of the repos. Are people
> able to help?
>
> Thanks everyone for getting on board (
>
> On 6/2/17, 2:44 AM, "Blair Bethwaite"  wrote:
>
> Hi Alex,
>
> Likewise for option 3. If I recall correctly from the summit session
> that was also the main preference in the room?
>
> On 2 June 2017 at 11:15, George Mihaiescu 
> wrote:
> > +1 for option 3
> >
> >
> >
> > On Jun 1, 2017, at 11:06, Alexandra Settle 
> wrote:
> >
> > Hi everyone,
> >
> >
> >
> > I haven’t had any feedback regarding moving the Operations Guide to
> the
> > OpenStack wiki. I’m not taking silence as compliance. I would really
> like to
> > hear people’s opinions on this matter.
> >
> >
> >
> > To recap:
> >
> >
> >
> > Option one: Kill the Operations Guide completely and move the
> Administration
> > Guide to project repos.
> > Option two: Combine the Operations and Administration Guides (and
> then this
> > will be moved into the project-specific repos)
> > Option three: Move Operations Guide to OpenStack wiki (for ease of
> > operator-specific maintainability) and move the Administration Guide
> to
> > project repos.
> >
> >
> >
> > Personally, I think that option 3 is more realistic. The idea for
> the last
> > option is that operators are maintaining operator-specific
> documentation and
> > updating it as they go along and we’re not losing anything by
> combining or
> > deleting. I don’t want to lose what we have by going with option 1,
> and I
> > think option 2 is just a workaround without fixing the problem – we
> are not
> > getting contributions to the project.
> >
> >
> >
> > Thoughts?
> >
> >
> >
> > Alex
> >
> >
> >
> > From: Alexandra Settle 
> > Date: Friday, May 19, 2017 at 1:38 PM
> > To: Melvin Hillsman , OpenStack Operators
> > 
> > Subject: Re: [Openstack-operators] Fwd: [openstack-dev]
> [openstack-doc]
> > [dev] What's up doc? Summit recap edition
> >
> >
> >
> > Hi everyone,
> >
> >
> >
> > Adding to this, I would like to draw your attention to the last dot
> point of
> > my email:
> >
> >
> >
> > “One of the key takeaways from the summit was the session that I
> joint
> > moderated with Melvin Hillsman regarding the Operations and
> Administration
> > Guides. You can find the etherpad with notes here:
> > https://etherpad.openstack.org/p/admin-ops-guides  The session was
> really
> > helpful – we were able to discuss with the operators present the
> current
> > situation of the documentation team, and how they could help us
> maintain the
> > two guides, aimed at the same audience. The operator’s present at the
> > session agreed that the Administration Guide was important, and
> could be
> > maintained upstream. However, they voted and agreed that the best
> course of
> > action for the Operations Guide was for it to be pulled down and put
> into a
> > wiki that the operators could manage themselves. We will be looking
> at
> > actioning this item as soon as possible.”
> >
> >
> >
> > I would like to go ahead with this, but I would appreciate feedback
> from
> > operators who were not able to attend the summit. In the etherpad
> you will
> > see the three options that the operators in the room recommended as
> being
> > viable, and the voted option being moving the Operations Guide out of
> > docs.openstack.org into a wiki. The aim of this was to empower the
> > operations community to take more control of the updates in an
> environment
> > they are more familiar with (and available to others).
> >
> >
> >
> > What does everyone think of the proposed options? Questions? Other
> thoughts?
> 

Re: [openstack-dev] [doc][ptls][all] Documentation publishing future

[Anne Gentle]

On Tue, May 23, 2017 at 8:56 AM, Zane Bitter  wrote:

> On 22/05/17 05:39, Alexandra Settle wrote:
>
>> 1. We could combine all of the documentation builds, so that each
>> project has a single doc/source directory that includes developer,
>> contributor, and user documentation. This option would reduce the number
>> of build jobs we have to run, and cut down on the number of separate
>> sphinx configurations in each repository. It would completely change the
>> way we publish the results, though, and we would need to set up
>> redirects from all of the existing locations to the new locations and
>> move all of the existing documentation under the new structure.
>>
>
> +0 in the short term, +1 for the long term
>
> 2. We could retain the existing trees for developer and API docs, and
>> add a new one for "user" documentation. The installation guide,
>> configuration guide, and admin guide would move here for all projects.
>> Neutron's user documentation would include the current networking guide
>> as well. This option would add 1 new build to each repository, but would
>> allow us to easily roll out the change with less disruption in the way
>> the site is organized and published, so there would be less work in the
>> short term.
>>
>
> +1, at least in the short term
>
> As we've been discussing since the summit, Heat has a bunch of
> documentation (specifically the Template Guide) that is end-user-facing but
> needs to be generated from the Heat repo (because it uses introspection on
> the code). Right now it's buried in the (OpenStack) developer-facing
> documentation, which is not very discoverable for end users. So generating
> the user guide from the project repos would allow us to move the Template
> Guide.


What prevents you from publishing to a different location? The landing page
or the URL or something else I'm not considering? The URL can be changed in
the publish job, I think, so what we really need are the "rules" and
organization. I already discovered at the PTG that we are not consistent
with version number and translation language in our URLs...

It's something we'll have to work on -- the usability of the landing pages
and the directories for the publish jobs and how those translate to URLs.
Thoughts?

Anne


>
>
> 3. We could do option 2, but use a separate repository for the new
>> user-oriented documentation. This would allow project teams to delegate
>> management of the documentation to a separate review project-sub-team,
>> but would complicate the process of landing code and documentation
>> updates together so that the docs are always up to date.
>>
>
> -1 for the reasons above.
>
> cheers,
> Zane.
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [doc][ptls][all] Documentation publishing future

[Anne Gentle]

On Mon, May 22, 2017 at 5:41 PM, Sean McGinnis 
wrote:

> On Mon, May 22, 2017 at 09:39:09AM +, Alexandra Settle wrote:
>
> [snip]
>
> > 1. We could combine all of the documentation builds, so that each
> project has a single doc/source directory that includes developer,
> contributor, and user documentation. This option would reduce the number of
> build jobs we have to run, and cut down on the number of separate sphinx
> configurations in each repository. It would completely change the way we
> publish the results, though, and we would need to set up redirects from all
> of the existing locations to the new locations and move all of the existing
> documentation under the new structure.
> >
> > 2. We could retain the existing trees for developer and API docs, and
> add a new one for "user" documentation. The installation guide,
> configuration guide, and admin guide would move here for all projects.
> Neutron's user documentation would include the current networking guide as
> well. This option would add 1 new build to each repository, but would allow
> us to easily roll out the change with less disruption in the way the site
> is organized and published, so there would be less work in the short term.
> >
> > 3. We could do option 2, but use a separate repository for the new
> user-oriented documentation. This would allow project teams to delegate
> management of the documentation to a separate review project-sub-team, but
> would complicate the process of landing code and documentation updates
> together so that the docs are always up to date.
> >
>
> I actually like the first two a little better, but I think this might
> actually be the best option. My hope
> would be that there could continue to be a docs team that can help out
> with some of this, and by having a
> separate repo it would allow usto set up separate teams with rights to
> merge.
>

Hey Sean, is the "right to merge" the top difficulty you envision with 1 or
2? Or is it finding people to do the writing and reviews? Curious about
your thoughts and if you have some experience with specific day-to-day
behavior here, I would love your insights.

Anne


>
> > Personally, I think option 2 or 3 are more realistic, for now. It does
> mean that an extra build would have to be maintained, but it retains that
> key differentiator between what is user and developer documentation and
> involves fewer changes to existing published contents and build jobs. I
> definitely think option 1 is feasible, and would be happy to make it work
> if the community prefers this. We could also view option 1 as the
> longer-term goal, and option 2 as an incremental step toward it (option 3
> would make option 1 more complicated to achieve).
> >
> > What does everyone think of the proposed options? Questions? Other
> thoughts?
> >
> > Cheers,
> >
> > Alex
> >
> >
>
> > 
> __
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [doc][ptls][all] Documentation publishing future

[Anne Gentle]

> On May 22, 2017, at 9:09 AM, Doug Hellmann  wrote:
>
> Excerpts from Dmitry Tantsur's message of 2017-05-22 12:26:25 +0200:
>>> On 05/22/2017 11:39 AM, Alexandra Settle wrote:
>>> Hi everyone,
>>>
>>> The documentation team are rapidly losing key contributors and core 
>>> reviewers.
>>> We are not alone, this is happening across the board. It is making things
>>> harder, but not impossible.
>>>
>>> Since our inception in 2010, we’ve been climbing higher and higher trying to
>>> achieve the best documentation we could, and uphold our high standards. 
>>> This is
>>> something to be incredibly proud of.
>>>
>>> However, we now need to take a step back and realise that the amount of 
>>> work we
>>> are attempting to maintain is now out of reach for the team size that we 
>>> have.
>>> At the moment we have 13 cores, of whom none are full time contributors or
>>> reviewers. This includes myself.
>>>
>>> Until this point, the documentation team has owned several manuals that 
>>> include
>>> content related to multiple projects, including an installation guide, admin
>>> guide, configuration guide, networking guide, and security guide. Because 
>>> the
>>> team no longer has the resources to own that content, we want to invert the
>>> relationship between the doc team and project teams, so that we become 
>>> liaisons
>>> to help with maintenance instead of asking for project teams to provide 
>>> liaisons
>>> to help with content. As a part of that change, we plan to move the existing
>>> content out of the central manuals repository, into repositories owned by 
>>> the
>>> appropriate project teams. Project teams will then own the content and the
>>> documentation team will assist by managing the build tools, helping with 
>>> writing
>>> guidelines and style, but not writing the bulk of the text.
>>>
>>> We currently have the infrastructure set up to empower project teams to 
>>> manage
>>> their own documentation in their own tree, and many do. As part of this 
>>> change,
>>> the rest of the existing content from the install guide and admin guide will
>>> also move into project-owned repositories. We have a few options for how to
>>> implement the move, and that's where we need feedback now.
>>>
>>> 1. We could combine all of the documentation builds, so that each project 
>>> has a
>>> single doc/source directory that includes developer, contributor, and user
>>> documentation. This option would reduce the number of build jobs we have to 
>>> run,
>>> and cut down on the number of separate sphinx configurations in each 
>>> repository.
>>> It would completely change the way we publish the results, though, and we 
>>> would
>>> need to set up redirects from all of the existing locations to the new
>>> locations and move all of the existing documentation under the new 
>>> structure.
>>>
>>> 2. We could retain the existing trees for developer and API docs, and add a 
>>> new
>>> one for "user" documentation. The installation guide, configuration guide, 
>>> and
>>> admin guide would move here for all projects. Neutron's user documentation 
>>> would
>>> include the current networking guide as well. This option would add 1 new 
>>> build
>>> to each repository, but would allow us to easily roll out the change with 
>>> less
>>> disruption in the way the site is organized and published, so there would be
>>> less work in the short term.
>>>
>>> 3. We could do option 2, but use a separate repository for the new 
>>> user-oriented
>>> documentation. This would allow project teams to delegate management of the
>>> documentation to a separate review project-sub-team, but would complicate 
>>> the
>>> process of landing code and documentation updates together so that the docs 
>>> are
>>> always up to date.
>>>
>>> Personally, I think option 2 or 3 are more realistic, for now. It does mean
>>> that an extra build would have to be maintained, but it retains that key
>>> differentiator between what is user and developer documentation and involves
>>> fewer changes to existing published contents and build jobs. I definitely 
>>> think
>>> option 1 is feasible, and would be happy to make it work if the community
>>> prefers this. We could also view option 1 as the longer-term goal, and 
>>> option 2
>>> as an incremental step toward it (option 3 would make option 1 more 
>>> complicated
>>> to achieve).
>>>
>>> What does everyone think of the proposed options? Questions? Other thoughts?
>>
>> We're already hosting install-guide and api-ref in our tree, and I'd prefer 
>> we
>> don't change it, as it's going to be annoying (especially wrt backports). I'd
>> prefer we create user-guide directory in projects, and move the user guide 
>> there.
>
> Handling backports with a merged guide is an issue we didn't come
> up with in our earlier discussions. How often do you backport doc
> changes in practice? Do you foresee merge conflicts caused by issues
> other than the files being renamed?
>

For 

Re: [openstack-dev] [doc][ptls][all] Documentation publishing future

[Anne Gentle]

On Mon, May 22, 2017 at 4:39 AM, Alexandra Settle 
wrote:

> Hi everyone,
>
>
>
> The documentation team are rapidly losing key contributors and core
> reviewers. We are not alone, this is happening across the board. It is
> making things harder, but not impossible.
>
> Since our inception in 2010, we’ve been climbing higher and higher trying
> to achieve the best documentation we could, and uphold our high standards.
> This is something to be incredibly proud of.
>
>
>
> However, we now need to take a step back and realise that the amount of
> work we are attempting to maintain is now out of reach for the team size
> that we have. At the moment we have 13 cores, of whom none are full time
> contributors or reviewers. This includes myself.
>

One point I'd like to emphasize with this proposal, any way we go, is that
we would prefer that the writing tasks not always fall on the devs, but
that there can be dedicated writers or ops or end-users attending to info
needs, it's just that they'll do the work in the repos.

Also, I'm working on a patch to try to quantify the best practices using
our current data: https://review.openstack.org/#/c/461280/ We may discover
some ways to work that mean gaining efficiencies and ensuring quality.
Project teams should consider changes to reviewers and so on to try to be
inclusive of the varied types of work in their repo.

I'll emphasize that we need to be extremely protective of the user space
with this sort of move. No one who reads the docs ultimately cares about
how they are put together. They just want to find what they need and get on
with their lives.


>
>
> Until this point, the documentation team has owned several manuals that
> include content related to multiple projects, including an installation
> guide, admin guide, configuration guide, networking guide, and security
> guide. Because the team no longer has the resources to own that content, we
> want to invert the relationship between the doc team and project teams, so
> that we become liaisons to help with maintenance instead of asking for
> project teams to provide liaisons to help with content. As a part of that
> change, we plan to move the existing content out of the central manuals
> repository, into repositories owned by the appropriate project teams.
> Project teams will then own the content and the documentation team will
> assist by managing the build tools, helping with writing guidelines
> and style, but not writing the bulk of the text.
>
>
>
> We currently have the infrastructure set up to empower project teams to
> manage their own documentation in their own tree, and many do. As part of
> this change, the rest of the existing content from the install guide and
> admin guide will also move into project-owned repositories. We have a few
> options for how to implement the move, and that's where we need feedback
> now.
>
>
>
> 1. We could combine all of the documentation builds, so that each project
> has a single doc/source directory that includes developer, contributor, and
> user documentation. This option would reduce the number of build jobs we
> have to run, and cut down on the number of separate sphinx configurations
> in each repository. It would completely change the way we publish the
> results, though, and we would need to set up redirects from all of the
> existing locations to the new locations and move all of the existing
> documentation under the new structure.
>

I'd love to try this one. I know this is what John Dickenson has tried for
the swift project with https://review.openstack.org/#/c/386834/ but since
it didn't match anyone else, and I haven't heard back yet about the user
experience, we didn't pursue much.

I'll still be pretty adamant about the user experience, so that the project
name does not spill over into the user space. Redirects will be crucial as
someone pointed out in one of the recent etherpads. Also, it may require
not publishing api-ref info to developer.openstack.org (in other words, one
job means one target for publication right now).


>
>
> 2. We could retain the existing trees for developer and API docs, and add
> a new one for "user" documentation. The installation guide, configuration
> guide, and admin guide would move here for all projects. Neutron's user
> documentation would include the current networking guide as well. This
> option would add 1 new build to each repository, but would allow us to
> easily roll out the change with less disruption in the way the site is
> organized and published, so there would be less work in the short term.
>
>
>
> 3. We could do option 2, but use a separate repository for the new
> user-oriented documentation. This would allow project teams to delegate
> management of the documentation to a separate review project-sub-team, but
> would complicate the process of landing code and documentation updates
> together so that the docs are always up to date.
>

It's possible the data could point us in 

[openstack-dev] [all] Consolidating web themes

[Anne Gentle]

Hi all,

I wanted to make you all aware of some consolidation efforts I'll be
working on this release. You may have noticed a new logo for OpenStack, and
perhaps you saw the update to the web design and headers on
docs.openstack.org as well.

To continue these efforts, I'll also be working on having all docs pages
use one theme, the openstackdocstheme, that has these latest updates.
Currently we are using version 1.8.0, and I'll do more releases as we
complete the UI consolidation.

I did an analysis to compare oslosphinx to openstackdocstheme, and I wanted
to let this group know about the upcoming changes so you can keep an eye
out for reviews. This effort will take a while, and I'd welcome help, of
course.

There are a few UI items that I don't plan port from oslosphinx to
openstackdocstheme:

Quick search form in bottom of left-hand navigation bar (though I'd welcome
a way to unify that UI and UX across the themes).
Previous topic and Next topic shown in left-hand navigation bar (these are
available in the openstackdocstheme in a different location).
Return to project home page link in left-hand navigation bar. (also would
welcome a design that fits well in the openstackdocstheme left-hand nav)
Customized list of links in header. For example, the page athttps://
docs.openstack.org/infra/system-config/ contains a custom header.
When a landing page like https://docs.openstack.org/infra/ uses oslosphinx,
the page should be redesigned with the new theme in mind.

I welcome input on these changes, as I'm sure I haven't caught every
scenario, and this is my first wider communication about the theme changes.
The spec for this work is detailed here: http://specs.openstack.
org/openstack/docs-specs/specs/pike/consolidating-themes.html

Let me know what I've missed, what you cannot live without, and please
reach out if you'd like to help.

Thanks,
Anne

--
Technical Product Manager, Cisco Metacloud
annegen...@justwriteclick.com
@annegentle
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [api] [docs] Contributor and reviewer stats for API docs

[Anne Gentle]

Hi all,

I've started a patch to the openstack-infra/reviewstats repo [1] to measure
the number of reviews, reviewers, contributors, and contributions to API
docs where the docs are housed in project repos.

A couple of goals can be realized if we know more: to determine the experts
in the speciality and to figure out if there are processes that can be
improved, or projects that can use extra help. And, to improve both the API
docs processes and content.

Both my Python and bash skills are rudimentary on a good day so I'd like to
get some help and learn at the same time so I can improve. Is the patch on
the right track? Is this the right repo to get data (or is it really for
reviews only)? Take a look and let me know.

Thanks in advance -
Anne

1. https://review.openstack.org/#/c/461280/

--

Read my blog: justwrite.click
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [devstack] [all] systemd in devstack by default

[Anne Gentle]

On Wed, May 3, 2017 at 6:14 PM, Sean Dague  wrote:

> On 05/03/2017 07:08 PM, Doug Hellmann wrote:
>
>> Excerpts from Sean Dague's message of 2017-05-03 16:16:29 -0400:
>>
>>> Screen is going away in Queens.
>>>
>>> Making the dev / test runtimes as similar as possible is really
>>> important. And there is so much weird debt around trying to make screen
>>> launch things reliably (like random sleeps) because screen has funny
>>> races in it.
>>>
>>> It does mean some tricks people figured out in screen are going away.
>>>
>>
>> It sounds like maybe we should start building a shared repository of new
>> tips & tricks for systemd/journald.
>>
>
> Agreed, the devstack docs have the following beginnings of that:
>
> https://docs.openstack.org/developer/devstack/development.html - for
> basic flow
>
> which also links to a systemd primer - https://docs.openstack.org/dev
> eloper/devstack/systemd.html
>
> But more contributions are welcomed for sure.
>
> (These docs exist in the devstack tree under doc/source)


Another set of docs that helped me figure out screen in DevStack are in the
Ops Guide [1][2]. Low-hanging fruit, the way I see it, so I've also logged
a doc bug[3].

Anne

1.
https://github.com/openstack/openstack-manuals/blob/master/doc/ops-guide/source/ops-customize-objectstorage.rst

2.
https://github.com/openstack/openstack-manuals/blob/master/doc/ops-guide/source/ops-customize-compute.rst

3. https://bugs.launchpad.net/openstack-manuals/+bug/1688245


>
>
> -Sean
>
> --
> Sean Dague
> http://dague.net
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [tc] [all] TC Report 18

[Anne Gentle]

On Wed, May 3, 2017 at 2:41 AM, Thierry Carrez 
wrote:

> Chris Dent wrote:
> >
> > # Intro
> >
> > Feedback from last week's first attempt at a weekly overview of TC
> > activity was positive enough to continue. Suggestions on how to make
> > it more useful welcome. Main change this time is that I've added
> > some information on stuff happened outside the meeting, a link to
> > the meeting minutes, and a section on stuff we talked about last
> > week that we said we'd pick up later but haven't yet.
> > [...]
>
> Thanks again for publishing your notes!
>
> That reminded me of an issue that has been bothering me for a while. We
> have one area that the current reviews+meeting system fails to capture
> well: issues that are raised somewhere in the community but do not take
> the shape of a formal resolution or governance change. In the current
> system, TC members (or really, anyone in the community) can add to the
> "Open discussion" section of the meeting agenda, but that happens
> extremely rarely. I suspect that the 5 minutes per week that we end up
> dedicating to open discussion in the meetings does not encourage people
> to load large topics of discussions in it. But it's a bit of a
> chicken-and-egg: I only keep a couple minutes of open discussion because
> nobody posts topics to discuss there on the agenda...
>

Would office hours work for this case? Might bring up random topics, but at
least the conversation could be real-time. Seems worth trying.

Thanks Chris for writing up notes! It's a tough job to summarize and this
is well-done.

Anne


>
> As we look toward evolving the meeting format, I feel like moving to a
> more free-form, less timeboxed forum for discussing TC topics (like a
> specific IRC channel or office hours in #openstack-dev) will allow us to
> raise such hot topics more easily.
>
> --
> Thierry Carrez (ttx)
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [magnum][osc] What name to use for magnum commands in osc?

[Anne Gentle]

On Mon, Mar 20, 2017 at 4:38 PM, Dean Troyer  wrote:

> On Mon, Mar 20, 2017 at 4:36 PM, Adrian Otto 
> wrote:
> > So, to be clear, this would result in the following command for what we
> currently use “magnum cluster create” for:
> >
> > openstack coe cluster create …
> >
> > Is this right?
>
> Yes.
>
>
This looks good to me as an OSC user.

One other question, I honestly can't remember if the projects.yaml name
needs to match the service catalog name? Might be a good time to synch
everything if so. Right now, it's "Container Infrastructure Management
service" and could be Container Orchestration Engine Management service.

Naming, it's hard.
Anne


> dt
>
> --
>
> Dean Troyer
> dtro...@gmail.com
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [OpenStack-docs] [docs][release][ptl] Adding docs to the release schedule

[Anne Gentle]

On Wed, Mar 1, 2017 at 11:52 AM, Alexandra Settle 
wrote:

> Hi everyone,
>
>
>
> I would like to propose that we introduce a “Review documentation” period
> on the release schedule.
>
>
>
> We would formulate it as a deadline, so that it fits in the schedule and
> making it coincide with the RC1 deadline.
>
>
>
> For projects that are not following the milestones, we would translate
> this new inclusion literally, so if you would like your project to be
> documented at docs.o.o, then doc must be introduced and reviewed one month
> before the branch is cut.
>

I like this idea, and it can align certain docs with string freeze
logically.

I think the docs that are governed with this set of rules should be scoped
only to those that are synched with a release, namely the Configuration
Reference, Networking Guide, and Install Guides. [1]

For reference, those are the guides that would best align with "common
cycle with development milestones." [2]

Scope this proposal to the released guides, clarify which repo those will
be in, who can review and merge, and precisely when the cutoff is, and
you're onto something here. Plus, I can hear the translation teams
cheering. :)

Anne


1.
https://docs.openstack.org/contributor-guide/blueprints-and-specs.html#release-specific-documentation

2.
https://docs.openstack.org/project-team-guide/release-management.html#common-cycle-with-development-milestones


>
> In the last week since we released Ocata, it has become increasingly
> apparent that the documentation was not updated from the development side.
> We were not aware of a lot of new enhancements, features, or major bug
> fixes for certain projects. This means we have released with
> incorrect/out-of-date documentation. This is not only an unfortunately bad
> reflection on our team, but on the project teams themselves.
>
>
>
> The new inclusion to the schedule may seem unnecessary, but a lot of
> people rely on this and the PTL drives milestones from this schedule.
>
>
>
> From our side, I endeavor to ensure our release managers are working
> harder to ping and remind doc liaisons and PTLs to ensure the documentation
> is appropriately updated and working to ensure this does not happen in the
> future.
>
>
>
> Thanks,
>
>
>
> Alex
>
>
>
> ___
> OpenStack-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [infra][all] Project Navigator Broken

[Anne Gentle]

Hi Kenny,
Best place to log a bug for www.openstack.org content is here:

https://bugs.launchpad.net/openstack-org

I also see zero count for projects on Chrome for Mac this morning.

Anne

On Thu, Feb 23, 2017 at 7:42 AM, Kenny Johnston 
wrote:

> The project navigator[1] is no longer displaying projects.
>
> --
> Kenny Johnston | irc:kencjohnston | @kencjohnston
> [1]https://www.openstack.org/software/project-navigator/
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Women-of-openstack] [OpenStack Marketing] Community Voting for the OpenStack Summit Boston Now Open!

[Anne Gentle]

I'm seeing the same, and logging a bug here:

https://bugs.launchpad.net/openstack-org/+bug/1665041

Anne

On Wed, Feb 15, 2017 at 10:28 AM, Swarna Podila (Avi Networks) <
swa...@avinetworks.com> wrote:

> Sorry for the mass reply, but I am not able to access the Vote For
> Speakers link.  Attached is the screenshot of what I see; the text box
> there is not editable (as in, I cannot enter anything into it).  I click on
> "Log in as someone else”, it logs me out, but brings me back to this same
> page when I try to log back in.
>
>
> Best,
> Swarna.
>
> On Feb 15, 2017, 8:23 AM -0800, Erin Disney , wrote:
>
> Hi everyone,
>
> Session voting is now open for the May 2017 OpenStack Summit in Boston!
>
> VOTE HERE 
>
> Hurry, voting closes Tuesday, February 21st 11:59pm PST (Wednesday,
> February 22 at 7:59am UTC).
>
> Please Note: Based on community feedback, unique URLs to submissions have
> been added back for this Summit.
>
> Track Chairs will ultimately determine the final schedule. Community votes
> are meant to help inform the decision, but are not considered to be the
> deciding factor. Track chairs exercise judgment in their area of expertise
> and help ensure diversity. View full details of the session selection
> process here
> 
> .
>
> Continue to visit https://www.openstack.org/summit/boston-2017/ for all
> Summit-related information.
>
> REGISTER
> Register HERE
> 
>  before
> prices increase in early March.
>
> TRAVEL SUPPORT PROGRAM
> March 6 is the last day to submit applications. Please submit your
> applications HERE
>  by
> 11:59pm PST (March 7 at 7:59am UTC).
>
> VISA APPLICATION PROCESS
> If you require a visa to travel to the United States, please carefully
> read the instructions HERE
> . All visa
> invitation letter requests must be received by April 17.
>
> BECOME A SPONSOR
> If you are interested in sponsoring the Summit as well, it's not too late.
> Please email sum...@openstack.org no later than March 13th.
>
>
> Erin Disney
> OpenStack Marketing
> e...@openstack.org
>
> ___
> Marketing mailing list
> market...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/marketing
>
>
> ___
> Women-of-openstack mailing list
> women-of-openst...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/women-of-openstack
>
>


-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [api] Retiring fairy-slipper, the conversion tool for API docs

[Anne Gentle]

Hi all,

I believe that with the migration from WADL to RST complete, the use case
for fairy-slipper has also come to a close. I plan to retire it.

Share any concerns or questions you have, and I'll use the standard process
[1] to retire the repo.

Anne

1. http://docs.openstack.org/infra/manual/drivers.html#retiring-a-project

-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Anne Gentle]

On Tue, Jan 3, 2017 at 10:47 AM, Doug Hellmann <d...@doughellmann.com>
wrote:

> Excerpts from Anne Gentle's message of 2017-01-03 10:26:28 -0600:
> > On Tue, Jan 3, 2017 at 12:04 AM, Andreas Jaeger <a...@suse.com> wrote:
> >
> > > On 01/03/2017 04:01 AM, Anne Gentle wrote:
> > > > [...]
> > > > Doug, I think the include in Sphinx can be a raw txt file? Then we
> get
> > > > the best of both worlds - rendered on both docs.openstack.org
> > > > <http://docs.openstack.org> and github.com <http://github.com>.
> > >
> > > We do not need an rst file, github handles .txt just fine. I see no
> > > reason to move to txt.
> > >
> > > > I'll give that a shot with these patches as a proof of concept:
> > > >
> > > > 1. Change cookie-cutter file to CONTRIBUTING.txt
> > > > https://review.openstack.org/416109
> > > > 2. Update openstack-manuals rendered docs with an included
> > > > CONTRIBUTING.txt https://review.openstack.org/416112
> > > >
> > > > We won't really know the GitHub UI rendering of the include until
> > > > merged, but I've tested in other repos and changing the file
> extension
> > > > to .txt gives a link to that file.
> > >
> > > Works with RST as well for me - I just created a pull request for
> > > cookiecutter and got the contributing link as expected. There's no need
> > > to use txt files.
> > >
> >
> > To wrap this up - I saw different behavior when simply clicking "New Pull
> > Request." The GitHub UI behaves differently for RST files in that
> > particular scenario, prior to the act of comparing branches. But it's not
> > worthwhile to pursue, and is probably simply a bug in GitHub's UI, so
> I've
> > abandoned the cookie-cutter patch.
>
> Ah, that's a case I didn't look at. So you're saying that if we
> call it CONTRIBUTING.txt then it renders on the page where the pull
> request is being created? That does seem like something we want.
>

What happens is you get a special notification and link to CONTRIBUTING.txt
(or rst, but only after comparing branches) as in this screenshot:

https://postimg.org/image/wple5yudr/

But, based on testing, it's fine to keep what we have (rst) for the
scenarios that work today.

Anne


>
> Doug
>
> >
> > Anne
> >
> > >
> > > > Thoughts? Please comment on the reviews or here. I can work on it if
> we
> > > > think it's worthwhile to standardize upon, and/or collaborate with
> the
> > > > original contributor who wanted to standardize. I do believe the
> GitHub
> > > > experience is worthy of attention, similar in my mind to the recent
> > > > badges work.
> > >
> > > 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: openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click <https://justwriteclick.com>
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Anne Gentle]

On Tue, Jan 3, 2017 at 12:04 AM, Andreas Jaeger <a...@suse.com> wrote:

> On 01/03/2017 04:01 AM, Anne Gentle wrote:
> > [...]
> > Doug, I think the include in Sphinx can be a raw txt file? Then we get
> > the best of both worlds - rendered on both docs.openstack.org
> > <http://docs.openstack.org> and github.com <http://github.com>.
>
> We do not need an rst file, github handles .txt just fine. I see no
> reason to move to txt.
>
> > I'll give that a shot with these patches as a proof of concept:
> >
> > 1. Change cookie-cutter file to CONTRIBUTING.txt
> > https://review.openstack.org/416109
> > 2. Update openstack-manuals rendered docs with an included
> > CONTRIBUTING.txt https://review.openstack.org/416112
> >
> > We won't really know the GitHub UI rendering of the include until
> > merged, but I've tested in other repos and changing the file extension
> > to .txt gives a link to that file.
>
> Works with RST as well for me - I just created a pull request for
> cookiecutter and got the contributing link as expected. There's no need
> to use txt files.
>

To wrap this up - I saw different behavior when simply clicking "New Pull
Request." The GitHub UI behaves differently for RST files in that
particular scenario, prior to the act of comparing branches. But it's not
worthwhile to pursue, and is probably simply a bug in GitHub's UI, so I've
abandoned the cookie-cutter patch.

Anne


>
> > Thoughts? Please comment on the reviews or here. I can work on it if we
> > think it's worthwhile to standardize upon, and/or collaborate with the
> > original contributor who wanted to standardize. I do believe the GitHub
> > experience is worthy of attention, similar in my mind to the recent
> > badges work.
>
> 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: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click <https://justwriteclick.com>
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Anne Gentle]

On Mon, Jan 2, 2017 at 11:03 AM, Doug Hellmann 
wrote:

> Excerpts from Paul Belanger's message of 2016-12-24 15:23:35 -0500:
> > On Wed, Dec 21, 2016 at 10:17:42AM -0600, Ian Cordasco wrote:
> > > -Original Message-
> > > From: Andrey Kurilin 
> > > Reply: OpenStack Development Mailing List (not for usage questions) <
> openstack-dev@lists.openstack.org>
> > > Date: December 21, 2016 at 10:13:09
> > > To: OpenStack Development Mailing List (not for usage questions) <
> openstack-dev@lists.openstack.org>
> > > Subject:  Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to
> projects
> > >
> > > > On Wed, Dec 21, 2016 at 5:46 PM, Andreas Jaeger wrote:
> > > >
> > > > > On 2016-12-21 16:22, Ian Cordasco wrote:
> > > > > > [...]
> > > > > > That said, I think there are two better places for this
> information
> > > > > > that are already standards in OpenStack:
> > > > > >
> > > > > > * README.rst
> > > > > > * HACKING.rst
> > > > > >
> > > > > > Most projects include links to the contributing documentation in
> at
> > > > > > least one of these files. I think the effort here is to
> standardize,
> > > > > > albeit in a brand new file, and that's admirable.
> > > > >
> > > > > If that's the goal - to standardize - then I would expect that we
> move
> > > > > all the documentation out of those files in one place.
> > > > >
> > > > > Right now, the changes duplicate information that exists - and the
> new
> > > > > information is often wrong. It points to place that do not exist or
> > > > > where better places exist. ;(
> > > > >
> > > >
> > > > Duplication can be reduced by using `.. include:: ` directive.
> > >
> > > That does not render anywhere except our documentation (via Sphinx).
> Git{Hub,Lab} don't render the include directive at all.
> > >
> > > So, no, that's not an option.
> > >
> > No, this is a valid option. We do it today with various documentation.
> >
> > They will however render to docs.o.o, which we consider source of truth.
> The
> > topic of rendering RST files to github has come up a few times, but each
> time
> > comes back to the fact we simply mirror to github.
> >
> > It is possible to have git.openstack.org render RST too, but we've
> opted to do
> > it with docs.openstack.org.
> >
>
> Using include works some places, but not others.
>
> The include directive is a feature of Sphinx, not docutils. We use
> Sphinx to convert reStructuredText to HTML for docs.o.o but github does
> not use Sphinx when rendering individual reStructuredText files such as
> CONTRIBUTING.rst or README.rst.
>
> Since the point of having CONTRIBUTING.rst be a separate file is
> to take advantage of the github.com integration to guide potential
> contributors to the right forum for their contributions, we need
> to ensure that those files render correctly by placing the content
> directly into those files.  Then we can have project contributor
> documentation use the include directive to avoid duplicating the
> information elsewhere.
>

Doug, I think the include in Sphinx can be a raw txt file? Then we get the
best of both worlds - rendered on both docs.openstack.org and github.com.

I'll give that a shot with these patches as a proof of concept:

1. Change cookie-cutter file to CONTRIBUTING.txt
https://review.openstack.org/416109
2. Update openstack-manuals rendered docs with an included CONTRIBUTING.txt
https://review.openstack.org/416112

We won't really know the GitHub UI rendering of the include until merged,
but I've tested in other repos and changing the file extension to .txt
gives a link to that file.

Thoughts? Please comment on the reviews or here. I can work on it if we
think it's worthwhile to standardize upon, and/or collaborate with the
original contributor who wanted to standardize. I do believe the GitHub
experience is worthy of attention, similar in my mind to the recent badges
work.

Anne


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



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Anne Gentle]

On Thu, Dec 22, 2016 at 10:47 AM, Andreas Jaeger <a...@suse.com> wrote:

> On 12/22/2016 04:52 PM, Anne Gentle wrote:
> >
> >
> > On Thu, Dec 22, 2016 at 8:32 AM, Doug Hellmann <d...@doughellmann.com
> > <mailto:d...@doughellmann.com>> wrote:
> >
> > Excerpts from Ian Cordasco's message of 2016-12-22 06:46:29 -0600:
> > >
> > > There is some ambiguity right now with projects as to where to put
> > > easy-to-find documentation (even if it is just a brief paragraph
> with
> > > a link to longer-form documentation) into our repositories. Let's
> > > focus on that discussion here. We can come up with a productive
> > > conclusion and work with this contributor. While you've chosen (and
> > > yes, you've chosen this) to have a negative assumption about this
> > > contributor's efforts, I've chosen to believe they're looking to
> fill
> > > a gap. Increasing the productivity of new contributors to
> OpenStack is
> > > a positive improvement for our community. It may not fix a bug or
> add
> > > a feature, but it helps ramp up the people who will do that.
> >
> > I thought we started adding these contributing files specifically
> > because of how they are rendered on github, as a way to try to
> prevent
> > folks from submitting pull requests there and then having them
> rejected
> > by the bot. It seemed more positive to give direction ahead of time
> than
> > through a rejection message.
> >
> >
> > +1 to this and Ian and Alex's sentiments.
> >
> > It'd be great to get people to click one more time (to a more specific
> > contributor guide), but let's face it, there has to be a lot of traffic
> > directly to github.com <http://github.com>. Let's make sure there's a
> > decent entry.
> >
> > Does anyone have a "perfect" CONTRIBUTING.rst (or does it need to be .md
> > for github, Ian?) for all projects? Is it similar to the nova 2012
> > version or is there a more modern take?
>
>
> I'm against *only* adding a CONTRIBUTING.rst file. Any such change,
> should remove the existing content so that we have no duplication. If we
> document in two or three places how to contribute, one will be out of sync.
>
> So, a well done patch would be welcome - but not just adding a file with
> wrong information and no integration into existing content,.
>


Sure, let's get accurate info, but the scenario I'm thinking of is this one:
https://help.github.com/articles/setting-guidelines-for-repository-contributors/

Where the link is automatically displayed.

Anne


>
> 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: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 

Read my blog: justwrite.click <https://justwriteclick.com>
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] Adding CONTRIBUTING.rst files to projects

[Anne Gentle]

On Thu, Dec 22, 2016 at 8:32 AM, Doug Hellmann 
wrote:

> Excerpts from Ian Cordasco's message of 2016-12-22 06:46:29 -0600:
> >
> > There is some ambiguity right now with projects as to where to put
> > easy-to-find documentation (even if it is just a brief paragraph with
> > a link to longer-form documentation) into our repositories. Let's
> > focus on that discussion here. We can come up with a productive
> > conclusion and work with this contributor. While you've chosen (and
> > yes, you've chosen this) to have a negative assumption about this
> > contributor's efforts, I've chosen to believe they're looking to fill
> > a gap. Increasing the productivity of new contributors to OpenStack is
> > a positive improvement for our community. It may not fix a bug or add
> > a feature, but it helps ramp up the people who will do that.
>
> I thought we started adding these contributing files specifically
> because of how they are rendered on github, as a way to try to prevent
> folks from submitting pull requests there and then having them rejected
> by the bot. It seemed more positive to give direction ahead of time than
> through a rejection message.
>

+1 to this and Ian and Alex's sentiments.

It'd be great to get people to click one more time (to a more specific
contributor guide), but let's face it, there has to be a lot of traffic
directly to github.com. Let's make sure there's a decent entry.

Does anyone have a "perfect" CONTRIBUTING.rst (or does it need to be .md
for github, Ian?) for all projects? Is it similar to the nova 2012 version
or is there a more modern take?

Anne


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



-- 

Read my blog: justwrite.click 
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all][ptls][tc][goals] community goals for Pike

[Anne Gentle]

, even if they
> have no
> > > work to do. Should we continue that way?
> > > - should we improve the guidance to achieve Goals?
> > >
> > > I created an etherpad if folks want to give feedback:
> > > https://etherpad.openstack.org/p/community-goals-ocata-feedback
> > >
> > > 2) Goals backlog - https://etherpad.openstack.
> org/p/community-goals
> > > - new Goals are highly welcome.
> > > - each Goal would be achievable in one cycle, if not I think we
> need
> > > to break it down into separated Goals (with connections).
> > > - some Goals already have a team (ex: Python 3) but some haven't.
> > > Maybe could we dress a list of people able to step-up and
> volunteer to
> > > help on these ones.
> > > - some Goals might require some documentation for how to achieve
> it.
> > >
> > > I think for now 2) can be discussed on the etherpad, though feel
> free
> > > to propose another channel.
> > >
> > > 3) Choose Goals for Pike.
> > > Some of us already did, but we might want to start looking at what
> > > Goals we would like to achieve during Pike cycle.
> > > I was thinking at giving a score to the Goals, that could be
> > > calculated by its priority (I know it's vague but we know what is
> > > really urgent for us versus what can wait 6 months); but also the
> > > number of people who are interested to contribute on a Goal (if
> this
> > > Goal doesn't have a team yet).
> > > For now, openstack/governance is the repository for Goals, please
> > > propose them here.
> > >
> > >
> > > Please give feedback, we're doing iterations here, and hopefully
> we'll
> > > improve our Community Goals over the next cycles.
> > > Thanks for your time,
> >
> > Two weeks happened, here's a digest version of the etherpad:
> >
> > - Most of projects achieved the goal for Ocata, and we saw strong
> > interest to do it on time
> > - Some confusion between the ACK'ing of a goal, and actually doing
> the work.
> > - Some projects were slow on the uptake (of starting the work) and
> > even reviewing the patches.
> > - For now, keep using openstack/governance repo for documenting
> Goals.
> > - Improve guidance on what projects are expected to do when updating
> > the status of the Goal.
> > - For each Goal, document who the "guides" are and how to find them
> > when help is needed.
> > - It seems like achieving multiple Goals in a single cycle wouldn't
> be
> > possible for all teams, we could prioritize them to let teams achieve
> > more than one Goal within a cycle.
> >
> > What's next?
> > https://etherpad.openstack.org/p/community-goals
> > Now that we have a good set of Goals that are proposed in this
> > etherpad, we might want to rank them by priority (1 is the most
> > important). Feel free to do it in the etherpad, by putting a rank in
> > "Priority rank".
> >
> > Also, I've noticed some Goals might be too big to be achievable
> within
> > a single cycle and might need to be split (Rolling upgrades for
> > example). If you're author of one these goals, please do so.
> > I hope we can start defining Pike Goals by next week, so we can start
> > documenting what we would expect and the guidance to achieve it/them.
> >
> > Any feedback is welcome,
> > --
> > Emilien Macchi
> >
> > 
> __
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:
> unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
> >
> >
> > 
> > Rackspace Limited is a company registered in England & Wales (company
> registered number 03897010) whose registered office is at 5 Millington
> Road, Hyde Park Hayes, Middlesex UB3 4AZ. Rackspace Limited privacy policy
> can be viewed at www.rackspace.co.uk/legal/privacy-policy - This e-mail
> message may contain confidential or privileged information intended for the
> recipient. Any dissemination, distribution or copying of the enclosed
> material is prohibited. If you receive this transmission in error, please
> notify us immediately by e-mail at ab...@rackspace.com and delete the
> original message. Your cooperation is appreciated.
> > 
> __
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:
> unsubscribe
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >
>
>
> --
> Sean Dague
> http://dague.net
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
--
Read my blog: justwrite.click <https://justwriteclick.com>
Subscribe to Docs|Code: docslikecode.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all][tc] Allowing Teams Based on Vendor-specific Drivers

[Anne Gentle]

On Tue, Nov 29, 2016 at 2:53 PM, Jeremy Stanley <fu...@yuggoth.org> wrote:

> On 2016-11-29 20:19:13 + (+), gordon chung wrote:
> [...]
> > i don't recall why they were moved to be officially under the Telemetry
> > umbrella[3] but i remember they weren't allowed to do something if they
> > weren't part of an 'official' project. if i could remember what it was
> > this paragraph would be a lot more useful.
> [...]
>
> Perhaps they wanted to publish documentation to the
> docs.openstack.org site? That's traditionally only been allowed by
> the Docs team for official project deliverables.
>

This is a false statement for driver docs. We have had a proprietary driver
docs policy [1] in place since 2015, which we collaborated on with driver
maintainers, wrote it down, and communicated broadly.

The summary is "If a vendor wants full documentation in the Configuration
Reference, they have to add to the wiki page a contact editor that will
take care of the vendor driver documentation. The Documentation team will
assign bugs to the contact person, include the contact person in reviews
for the vendor driver, and expects timely responses."

The way I see it, soft white, understanding that "level playing field" is
not exactly the end-goal for OpenStack but that great, tested and
functional features are, is a compelling way forward. We need
accountability, and I do think drivers are important and teams should find
ways to enable that work in meaningful ways while also not overwhelming the
common. Believe me the docs team has lived this and empathizes with the
concerns.

Anne

1. https://specs.openstack.org/openstack/docs-specs/
specs/kilo/move-driver-docs.html



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

-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all][ptls][tc][goals] acknowledging community goals for Ocata

[Anne Gentle]

On Wed, Nov 16, 2016 at 10:21 AM, Anne Gentle <annegen...@justwriteclick.com
> wrote:

>
>
>
> On Wed, Nov 16, 2016 at 9:35 AM, Doug Hellmann <d...@doughellmann.com>
> wrote:
>
>> We still have quite a few teams who have not acknowledged the goal for
>> Ocata. Remember, *all* teams are expected to respond, even if there is
>> no work to be done. The most important feature of this new process is
>> communication, which won't happen if teams don't participate.
>>
>> Please take a few minutes to review
>> http://governance.openstack.org/goals/index.html and
>> http://governance.openstack.org/goals/ocata/remove-incubated
>> -oslo-code.html
>> then submit a patch to add your planning artifacts to
>> openstack/governance/goals/ocata/remove-incubated-oslo-code.rst before
>> the deadline tomorrow.
>>
>
> Hi all,
>
> I wanted to follow up to let you know that Doug and I recorded a short
> video to talk about this new process and how we envision the community
> working together on this very first attempt at writing down expectations
> and setting up this new goal program.
>
> It's about 3 minutes and hopefully it'll help us all understand how to get
> the goals across the finish line. If you need more info, always feel free
> to reach out and ask. We'll iterate as we go.
>


And... now with an actual video link!

https://www.youtube.com/watch?v=tW0mJZe6Jiw


>
> Thanks,
> Anne
>
>
>>
>> Doug
>>
>> 
>> __
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscrib
>> e
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
>
> --
> Anne Gentle
> www.justwriteclick.com
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all][ptls][tc][goals] acknowledging community goals for Ocata

[Anne Gentle]

On Wed, Nov 16, 2016 at 9:35 AM, Doug Hellmann <d...@doughellmann.com>
wrote:

> We still have quite a few teams who have not acknowledged the goal for
> Ocata. Remember, *all* teams are expected to respond, even if there is
> no work to be done. The most important feature of this new process is
> communication, which won't happen if teams don't participate.
>
> Please take a few minutes to review
> http://governance.openstack.org/goals/index.html and
> http://governance.openstack.org/goals/ocata/remove-
> incubated-oslo-code.html
> then submit a patch to add your planning artifacts to
> openstack/governance/goals/ocata/remove-incubated-oslo-code.rst before
> the deadline tomorrow.
>

Hi all,

I wanted to follow up to let you know that Doug and I recorded a short
video to talk about this new process and how we envision the community
working together on this very first attempt at writing down expectations
and setting up this new goal program.

It's about 3 minutes and hopefully it'll help us all understand how to get
the goals across the finish line. If you need more info, always feel free
to reach out and ask. We'll iterate as we go.

Thanks,
Anne


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



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] [release] project documentation updates not RC-worthy

[Anne Gentle]

On Fri, Sep 30, 2016 at 10:23 AM, Brian Rosmaita <
brian.rosma...@rackspace.com> wrote:

> Just want to send out a quick recap of a discussion in #openstack-meeting
> during the release team meeting this morning, in case any other projects
> are in a similar situation.
>
> As you're aware, the api-ref was moved out of docs and into the source
> code tree for each project this cycle.  Since the api-ref on openstack.org
> is published from master, my plan for Glance was to make sure all
> revisions for newton were merged into master before 6 Oct ... but I did
> not make it a priority for RC time.  Thus we have a not completely
> up-to-date api-ref in the stable/newton source tree, and this morning I
> panicked, thinking that maybe we need a new RC.
>
> The consensus was that fixing the in-tree docs is not a critical issue, so
> no new RC.  Instead, the update should be addressed later in a newton
> point release.
>
>
Thanks for communicating this point. I will add it to the API guides
contributor information for future reference.

Will you backport those doc changes to stable/newton so the published
version is accurate? Or does everyone only publish from master anyway? We
can start working on "stable branch" publishing next, if teams want it.

Anne


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



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api][doc][neutron] what releases should API reference support?

[Anne Gentle]

On Tue, Sep 6, 2016 at 10:44 AM, Ihar Hrachyshka <ihrac...@redhat.com>
wrote:

> Alexander <alexander.bashma...@intel.com> wrote:
>
> FYI,
>>
>> A similar discussion was held for an api-ref change in Glance:
>> https://review.openstack.org/#/c/356693/
>>
>
> Thanks for the link, it led me to this discussion:
> http://lists.openstack.org/pipermail/openstack-dev/2016-August/101501.html
>
> From the looks of it, seems like the result of the discussion is glance
> folks tagging new API with micro-versions. In Neutron, we don’t have
> micro-versioning, though we have /extensions API that would allow to detect
> if a particular API is available. In particular case of dropping lbaasv1,
> it would mean we keep reference for the API for some time while stating
> it’s never available in Newton+?


Glance does not have microversioning either.

Yes, you need to keep the API reference for quite a long time (years). In
one page, note that the API version for the service is not available for
deployment in Newton+.

Anne


>
>
> Ihar
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [api] [all] New landing page for API docs collection

[Anne Gentle]

Hi all,
I've put together a solution for your review to replace
developer.openstack.org/api-ref.html with a new landing page. My idea is to
repurpose this page: http://developer.openstack.org/api-guide/quick-start/
as a collection point for all the API information. Once this lands, I will
redirect developer.openstack.org/api-ref.html to this new page.

Review is here:
https://review.openstack.org/#/c/361480/

Some projects are not in the list due to not having an API reference page
that is published to developer.openstack.org. Top of mind are cinder and
telemetry as you're super close and only need a little bit more work to get
over the line. I'm happy to get you where you want to be, just let me know
what you need.

Let me know your thoughts on how to get all the APIs in a single page as a
good starting point for consumers.
Thanks,
Anne

-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [cinder] [neutron] [ironic] [api] [doc] API status report

[Anne Gentle]

Hi cinder block storage peeps:

I haven't heard from you on your comfort level with publishing so I went
ahead and made the publishing job myself with this review:

https://review.openstack.org/361475

Please let me know your thoughts there. Is the document ready to publish?
Need anything else to get comfy? Let me know.

Thanks,
Anne

On Thu, Aug 11, 2016 at 7:52 AM, Anne Gentle <annegen...@justwriteclick.com>
wrote:

>
>
> On Wed, Aug 10, 2016 at 2:49 PM, Anne Gentle <
> annegen...@justwriteclick.com> wrote:
>
>> Hi all,
>> I wanted to report on status and answer any questions you all have about
>> the API reference and guide publishing process.
>>
>> The expectation is that we provide all OpenStack API information on
>> developer.openstack.org. In order to meet that goal, it's simplest for
>> now to have all projects use the RST+YAML+openstackdocstheme+os-api-ref
>> extension tooling so that users see available OpenStack APIs in a sidebar
>> navigation drop-down list.
>>
>> --Migration--
>> The current status for migration is that all WADL content is migrated
>> except for trove. There is a patch in progress and I'm in contact with the
>> team to assist in any way. https://review.openstack.org/#/c/316381/
>>
>> --Theme, extension, release requirements--
>> The current status for the theme, navigation, and Sphinx extension
>> tooling is contained in the latest post from Graham proposing a solution
>> for the release number switchover and offers to help teams as needed:
>> http://lists.openstack.org/pipermail/openstack-dev/2016-Augu
>> st/101112.html I hope to meet the requirements deadline to get those
>> changes landed. Requirements freeze is Aug 29.
>>
>> --Project coverage--
>> The current status for project coverage is that these projects are now
>> using the RST+YAML in-tree workflow and tools and publishing to
>> http://developer.openstack.org/api-ref/ so they will be
>> included in the upcoming API navigation sidebar intended to span all
>> OpenStack APIs:
>>
>> designate http://developer.openstack.org/api-ref/dns/
>> glance http://developer.openstack.org/api-ref/image/
>> heat http://developer.openstack.org/api-ref/orchestration/
>> ironic http://developer.openstack.org/api-ref/baremetal/
>> keystone http://developer.openstack.org/api-ref/identity/
>> manila http://developer.openstack.org/api-ref/shared-file-systems/
>> neutron-lib http://developer.openstack.org/api-ref/networking/
>> nova http://developer.openstack.org/api-ref/compute/
>> sahara http://developer.openstack.org/api-ref/data-processing/
>> senlin http://developer.openstack.org/api-ref/clustering/
>> swift http://developer.openstack.org/api-ref/object-storage/
>> zaqar http://developer.openstack.org/api-ref/messaging/
>>
>> These projects are using the in-tree workflow and common tools, but do
>> not have a publish job in project-config in the jenkins/jobs/projects.yaml
>> file.
>>
>> ceilometer
>>
>
> Sorry, in reviewing further today I found another project that does not
> have a publish job but has in-tree source files:
>
> cinder
>
> Team cinder: can you let me know where you are in your publishing comfort
> level? Please add an api-ref-jobs: line with a target of block-storage
> to jenkins/jobs/projects.yaml in the project-config repo to ensure
> publishing is correct.
>
> Another issue is the name of the target directory for the final URL. Team
> ironic can I change your api-ref-jobs: line to bare-metal instead of
> baremetal? It'll be better for search engines and for alignment with the
> other projects URLs: https://review.openstack.org/354135
>
> I've also uncovered a problem where a neutron project's API does not have
> an official service name, and am working on a solution but need help from
> the neutron team: https://review.openstack.org/#/c/351407
> Thanks,
> Anne
>
>
>>
>> --Projects not using common tooling--
>> These projects have API docs but are not yet using the common tooling, as
>> far as I can tell. Because of the user experience, I'm making a judgement
>> call that these cannot be included in the common navigation. I have patched
>> the projects.yaml file in the governance repo with the URLs I could
>> screen-scrape, but if I'm incorrect please do patch the projects.yaml in
>> the governance repo.
>>
>> astara
>> cloudkitty
>> congress
>> magnum
>> mistral
>> monasca
>> solum
>> tacker
>> trove
>>
>> Please reach out if you have questions or need assistance getting started
>> with the new common

Re: [openstack-dev] [all] versioning the api-ref?

[Anne Gentle]

On Fri, Aug 26, 2016 at 7:46 AM, Bashmakov, Alexander <
alexander.bashma...@intel.com> wrote:

> Any more feedback on this?
>

Hi, I've added a comment on the review. For now, inline text descriptions
are best for the context of what you're adding in that particular place.

Anne


>
> > On Aug 18, 2016, at 10:30 AM, Bashmakov, Alexander <
> alexander.bashma...@intel.com> wrote:
> >
> > Concrete example of an api-ref difference between Mitaka and Newton:
> > https://review.openstack.org/#/c/356693/1/api-ref/source/v2/
> images-parameters.yaml
> >
> > -Original Message-
> > From: Sean Dague [mailto:s...@dague.net]
> > Sent: Thursday, August 18, 2016 10:20 AM
> > To: Nikhil Komawar <nik.koma...@gmail.com>; OpenStack Development
> Mailing List (not for usage questions) <openstack-dev@lists.openstack.org>
> > Subject: Re: [openstack-dev] [all] versioning the api-ref?
> >
> >> On 08/18/2016 11:57 AM, Nikhil Komawar wrote:
> >> I guess the intent was to indicate the need for indicating the micro
> >> or in case of Glance minor version bump when required.
> >>
> >> The API isn't drastically different, there are new and old elements as
> >> shown in the Nova api ref linked.
> >
> > Right, so the point is that it should all be describable in a single
> document. It's like the fact that when you go to python API docs you get
> things like - https://docs.python.org/2/library/wsgiref.html
> >
> > "New in version 2.5."
> >
> > Perhaps if there is a concrete example of the expected differences
> between what would be in the mitaka tree vs. newton tree was can figure out
> an appropriate way to express that in api-ref.
> >
> >-Sean
> >
> > --
> > Sean Dague
> > http://dague.net
> >
> > 
> __
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe: openstack-dev-requ...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [api] Example HTTP status codes for review

[Anne Gentle]

Hi all,
To give projects a head start and a path to copy/paste to success, I've got
a sample HTTP status code YAML file that you can use with the os-api-ref
Sphinx extension to make nicely-styled HTML tables. Please take a look at
https://review.openstack.org/#/c/351835/

The idea here isn't to force projects to use a common description for
status codes but rather to give the current 25 OpenStack REST APIs a common
starting point for consistency. Read the update to the docs to gain an
understanding of its use: https://review.openstack.org/#/c/351794/

Thanks,
Anne

-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [OpenStack-docs] [Magnum] Using common tooling for API docs

[Anne Gentle]

On Fri, Aug 19, 2016 at 2:27 AM, Shuu Mutou <shu-mu...@rf.jp.nec.com> wrote:

> >   AFAIK, the API WG adopted Swagger (OpenAPI) as common tool for API
> > docs.
> >   Anne, has not the adoption been changed? Otherwise, do we need to
> > maintain much RST files also?
> >
> >
> >
> > It does say either/or in the API WG guideline:
> > http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html
>
> Yes. Also Ken'ichi Omichi said.
>
>
> > This isn't about a contest between projects for the best approach. This
> > is about serving end-users the best information we can.
>
> Yes. Correct information is the best information. The Accuracy is more
> important than web experience. When I was a user (and SIer), the document
> accuracy had not been kept. So we had to read source code at last. And now,
> as a developer (mainly UI plugins), I don't want maintain overlapped
> content several times (API source code, API reference, helps in client,
> helps in WebUI, etc). So I spend efforts to the spec auto-generation.
>
>
> > I'm reporting what I'm seeing from a broader viewpoint than a single
> project.
> > I don't have a solution other than RST/YAML for common navigation, and
> I'm
> > asking you to provide ideas for that integration point.
> >
> > My vision is that even if you choose to publish with OpenAPI, you would
> > find a way to make this web experience better. We can do better than this
> > scattered approach. I'm asking you to find a way to unify and consider
> the
> > web experience of a consumer of OpenStack services. Can you generate HTML
> > that can plug into the openstackdocstheme we are providing as a common
> tool?
>
> I need to know about the "common tools". Please, let me know what is
> difference between HTMLs built by Lars's patch and by common tools? Or can
> fairy-slipper do that from OpenAPI file?
>
>
Sure, sounds like there's some info missing that I can clarify.

All HTML built for OpenStack sites are copied via FTP. There's no
difference except for the CSS and JavaScript provided by openstackdocstheme
and built by os-api-ref.

Fairy-slipper is no longer being worked on as a common solution to serving
all OpenStack API information. It was used for migration purposes.

Lars's patch could find a way to use the CSS and JS to create a seamless
experience for end-users.

Anne



>
> Thanks,
> Shu
>
>
> > -Original Message-
> > From: Anne Gentle [mailto:annegen...@justwriteclick.com]
> > Sent: Wednesday, August 17, 2016 11:55 AM
> > To: Mutou Shuu(武藤 周) <shu-mu...@rf.jp.nec.com>
> > Cc: openstack-dev@lists.openstack.org; m...@redhat.com; Katou Haruhiko(加
> > 藤 治彦) <har-ka...@ts.jp.nec.com>; openstack-d...@lists.openstack.org;
> > kenichi.omi...@necam.com
> > Subject: Re: [OpenStack-docs] [openstack-dev] [Magnum] Using common
> > tooling for API docs
> >
> >
> >
> > On Tue, Aug 16, 2016 at 1:05 AM, Shuu Mutou <shu-mu...@rf.jp.nec.com
> > <mailto:shu-mu...@rf.jp.nec.com> > wrote:
> >
> >
> >   Hi Anne,
> >
> >   AFAIK, the API WG adopted Swagger (OpenAPI) as common tool for API
> > docs.
> >   Anne, has not the adoption been changed? Otherwise, do we need to
> > maintain much RST files also?
> >
> >
> >
> > It does say either/or in the API WG guideline:
> > http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html
> >
> >
> >
> >   IMO, for that the reference and the source code doesn't have
> > conflict, these should be near each other as possible as follow. And it
> > decreases maintainance costs for documents, and increases document
> > reliability. So I believe our approach is more ideal.
> >
> >
> >
> >
> > This isn't about a contest between projects for the best approach. This
> > is about serving end-users the best information we can.
> >
> >
> >   The Best: the references generated from source code.
> >
> >
> >
> > I don't want to argue, but anything generated from the source code
> suffers
> > if the source code changes in a way that reviewers don't catch as a
> > backwards-incompatible change you can break your contract.
> >
> >
> >   Better: the references written in docstring.
> >
> >   We know some projects abandoned these approach, and then they uses
> > RST + YAML.
> >   But we hope decreasing maintainance cost for the documents. So we
> > should not create so much RST files, I think.
> >
> >
> >
> >
> > I think

Re: [openstack-dev] [OpenStack-docs] [neutron] [api] [doc] API reference for neutron stadium projects (re: API status report)

[Anne Gentle]

On Thu, Aug 18, 2016 at 3:33 AM, Akihiro Motoki <amot...@gmail.com> wrote:

> 2016-08-13 7:36 GMT+09:00 Anne Gentle <annegen...@justwriteclick.com>:
> >
> >
> > On Fri, Aug 12, 2016 at 3:29 AM, Akihiro Motoki <amot...@gmail.com>
> wrote:
> >>
> >> this mail focuses on neutron-specific topics. I dropped cinder and
> ironic
> >> tags.
> >>
> >> 2016-08-11 23:52 GMT+09:00 Anne Gentle <annegen...@justwriteclick.com>:
> >> >
> >> >
> >> > On Wed, Aug 10, 2016 at 2:49 PM, Anne Gentle
> >> > <annegen...@justwriteclick.com>
> >> > wrote:
> >> >>
> >> >> Hi all,
> >> >> I wanted to report on status and answer any questions you all have
> >> >> about
> >> >> the API reference and guide publishing process.
> >> >>
> >> >> The expectation is that we provide all OpenStack API information on
> >> >> developer.openstack.org. In order to meet that goal, it's simplest
> for
> >> >> now
> >> >> to have all projects use the RST+YAML+openstackdocstheme+os-api-ref
> >> >> extension tooling so that users see available OpenStack APIs in a
> >> >> sidebar
> >> >> navigation drop-down list.
> >> >>
> >> >> --Migration--
> >> >> The current status for migration is that all WADL content is migrated
> >> >> except for trove. There is a patch in progress and I'm in contact
> with
> >> >> the
> >> >> team to assist in any way. https://review.openstack.org/#/c/316381/
> >> >>
> >> >> --Theme, extension, release requirements--
> >> >> The current status for the theme, navigation, and Sphinx extension
> >> >> tooling
> >> >> is contained in the latest post from Graham proposing a solution for
> >> >> the
> >> >> release number switchover and offers to help teams as needed:
> >> >>
> >> >> http://lists.openstack.org/pipermail/openstack-dev/2016-
> August/101112.html I
> >> >> hope to meet the requirements deadline to get those changes landed.
> >> >> Requirements freeze is Aug 29.
> >> >>
> >> >> --Project coverage--
> >> >> The current status for project coverage is that these projects are
> now
> >> >> using the RST+YAML in-tree workflow and tools and publishing to
> >> >> http://developer.openstack.org/api-ref/ so they will be
> >> >> included in the upcoming API navigation sidebar intended to span all
> >> >> OpenStack APIs:
> >> >>
> >> >> designate http://developer.openstack.org/api-ref/dns/
> >> >> glance http://developer.openstack.org/api-ref/image/
> >> >> heat http://developer.openstack.org/api-ref/orchestration/
> >> >> ironic http://developer.openstack.org/api-ref/baremetal/
> >> >> keystone http://developer.openstack.org/api-ref/identity/
> >> >> manila http://developer.openstack.org/api-ref/shared-file-systems/
> >> >> neutron-lib http://developer.openstack.org/api-ref/networking/
> >> >> nova http://developer.openstack.org/api-ref/compute/
> >> >> sahara http://developer.openstack.org/api-ref/data-processing/
> >> >> senlin http://developer.openstack.org/api-ref/clustering/
> >> >> swift http://developer.openstack.org/api-ref/object-storage/
> >> >> zaqar http://developer.openstack.org/api-ref/messaging/
> >> >>
> >> >> These projects are using the in-tree workflow and common tools, but
> do
> >> >> not
> >> >> have a publish job in project-config in the
> jenkins/jobs/projects.yaml
> >> >> file.
> >> >>
> >> >> ceilometer
> >> >
> >> >
> >> > Sorry, in reviewing further today I found another project that does
> not
> >> > have
> >> > a publish job but has in-tree source files:
> >> >
> >> > cinder
> >> >
> >> > Team cinder: can you let me know where you are in your publishing
> >> > comfort
> >> > level? Please add an api-ref-jobs: line with a target of block-storage
> >> > to
> >> > jenkins/jobs/projects.yaml in the project-config repo to ensure
> >> > publishing
> >> > is correct.
> >> >
> >>

Re: [openstack-dev] [OpenStack-docs] [Magnum] Using common tooling for API docs

[Anne Gentle]

On Tue, Aug 16, 2016 at 1:05 AM, Shuu Mutou <shu-mu...@rf.jp.nec.com> wrote:

> Hi Anne,
>
> AFAIK, the API WG adopted Swagger (OpenAPI) as common tool for API docs.
> Anne, has not the adoption been changed? Otherwise, do we need to maintain
> much RST files also?
>

It does say either/or in the API WG guideline:
http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html


>
> IMO, for that the reference and the source code doesn't have conflict,
> these should be near each other as possible as follow. And it decreases
> maintainance costs for documents, and increases document reliability. So I
> believe our approach is more ideal.
>
>
This isn't about a contest between projects for the best approach. This is
about serving end-users the best information we can.


> The Best: the references generated from source code.
>

I don't want to argue, but anything generated from the source code suffers
if the source code changes in a way that reviewers don't catch as a
backwards-incompatible change you can break your contract.


> Better: the references written in docstring.
>
> We know some projects abandoned these approach, and then they uses RST +
> YAML.
> But we hope decreasing maintainance cost for the documents. So we should
> not create so much RST files, I think.
>
>
I think you'll see the evolution of our discussions over the years has
brought us to this point in time. Yes, there are trade-offs in these
decisions.


> I'm proceeding auto-generation of swagger spec from magnum source code
> using pecan-swagger [1], and improving pecan-swagger with Michael McCune
> [2].
> These will generate almost Magnum API specs automatically in OpenAPI
> format.
> Also, these approach can be adopted by other APIs that uses pecan and WSME.
> Please check this also.
>

I ask you to consider the experience of someone consuming the API documents
OpenStack provides. There are 26 REST API services under an OpenStack
umbrella. Twelve of them will be included in an unified side-bar navigation
on developer.openstack.org due to using Sphinx tooling provided as a common
web experience. Six of them don't have redirects yet from the "old way" to
do API reference docs. Seven of them are not collected under a single
landing page or common sidebar or navigation. Three of them have no API
docs published to a website.

I'm reporting what I'm seeing from a broader viewpoint than a single
project. I don't have a solution other than RST/YAML for common navigation,
and I'm asking you to provide ideas for that integration point.

My vision is that even if you choose to publish with OpenAPI, you would
find a way to make this web experience better. We can do better than this
scattered approach. I'm asking you to find a way to unify and consider the
web experience of a consumer of OpenStack services. Can you generate HTML
that can plug into the openstackdocstheme we are providing as a common tool?
Thanks,
Anne


>
> [1] https://review.openstack.org/#/c/303235/
> [2] https://github.com/elmiko/pecan-swagger/
>
> Regards,
> Shu
>
>
> > -Original Message-
> > From: Anne Gentle [mailto:annegen...@justwriteclick.com]
> > Sent: Monday, August 15, 2016 11:00 AM
> > To: Hongbin Lu <hongbin...@huawei.com>
> > Cc: openstack-dev@lists.openstack.org; enstack.org
> > <openstack-d...@lists.openstack.org>
> > Subject: Re: [openstack-dev] [OpenStack-docs] [Magnum] Using common
> > tooling for API docs
> >
> > Hi Hongbin,
> >
> > Thanks for asking. I'd like for teams to look for ways to innovate and
> > integrate with the navigation as a good entry point for OpenAPI to become
> > a standard for OpenStack to use. That said, we have to move forward and
> > make progress.
> >
> > Is Lars or anyone on the Magnum team interested in the web development
> work
> > to integrate with the sidebar? See the work at
> > https://review.openstack.org/#/c/329508 and my comments on
> > https://review.openstack.org/#/c/351800/ saying that I would like teams
> > to integrate first to provide the best web experience for people
> consuming
> > the docs.
> >
> > Anne
> >
> > On Fri, Aug 12, 2016 at 4:43 PM, Hongbin Lu <hongbin...@huawei.com
> > <mailto:hongbin...@huawei.com> > wrote:
> >
> >
> >   Hi team,
> >
> >
> >
> >   As mentioned in the email below, Magnum are not using common
> tooling
> > for generating API docs, so we are excluded from the common navigation of
> > OpenStack API. I think we need to prioritize the work to fix it. BTW, I
> > notice there is a WIP patch [1] for generating API docs by using Swagger.
> > However, I am not sure if Swagge

Re: [openstack-dev] [OpenStack-docs] [Magnum] Using common tooling for API docs

[Anne Gentle]

Hi Hongbin,

Thanks for asking. I'd like for teams to look for ways to innovate and
integrate with the navigation as a good entry point for OpenAPI to become a
standard for OpenStack to use. That said, we have to move forward and make
progress.

Is Lars or anyone on the Magnum team interested in the web development work
to integrate with the sidebar? See the work at
https://review.openstack.org/#/c/329508 and my comments on
https://review.openstack.org/#/c/351800/ saying that I would like teams to
integrate first to provide the best web experience for people consuming the
docs.

Anne

On Fri, Aug 12, 2016 at 4:43 PM, Hongbin Lu <hongbin...@huawei.com> wrote:

> Hi team,
>
>
>
> As mentioned in the email below, Magnum are not using common tooling for
> generating API docs, so we are excluded from the common navigation of
> OpenStack API. I think we need to prioritize the work to fix it. BTW, I
> notice there is a WIP patch [1] for generating API docs by using Swagger.
> However, I am not sure if Swagger belongs to “common tooling” (docs team,
> please confirm).
>
>
>
> [1] https://review.openstack.org/#/c/317368/
>
>
>
> Best regards,
>
> Hongbin
>
>
>
> *From:* Anne Gentle [mailto:annegen...@justwriteclick.com]
> *Sent:* August-10-16 3:50 PM
> *To:* OpenStack Development Mailing List; openstack-docs@lists.
> openstack.org
> *Subject:* [openstack-dev] [api] [doc] API status report
>
>
>
> Hi all,
>
> I wanted to report on status and answer any questions you all have about
> the API reference and guide publishing process.
>
>
>
> The expectation is that we provide all OpenStack API information on
> developer.openstack.org. In order to meet that goal, it's simplest for
> now to have all projects use the RST+YAML+openstackdocstheme+os-api-ref
> extension tooling so that users see available OpenStack APIs in a sidebar
> navigation drop-down list.
>
>
>
> --Migration--
>
> The current status for migration is that all WADL content is migrated
> except for trove. There is a patch in progress and I'm in contact with the
> team to assist in any way. https://review.openstack.org/#/c/316381/
>
>
>
> --Theme, extension, release requirements--
>
> The current status for the theme, navigation, and Sphinx extension tooling
> is contained in the latest post from Graham proposing a solution for the
> release number switchover and offers to help teams as needed:
> http://lists.openstack.org/pipermail/openstack-dev/2016-August/101112.html
> I hope to meet the requirements deadline to get those changes landed.
> Requirements freeze is Aug 29.
>
>
>
> --Project coverage--
>
> The current status for project coverage is that these projects are now
> using the RST+YAML in-tree workflow and tools and publishing to
> http://developer.openstack.org/api-ref/ so they will be
> included in the upcoming API navigation sidebar intended to span all
> OpenStack APIs:
>
>
>
> designate http://developer.openstack.org/api-ref/dns/
>
> glance http://developer.openstack.org/api-ref/image/
> heat http://developer.openstack.org/api-ref/orchestration/
> ironic http://developer.openstack.org/api-ref/baremetal/
> keystone http://developer.openstack.org/api-ref/identity/
> manila http://developer.openstack.org/api-ref/shared-file-systems/
> neutron-lib http://developer.openstack.org/api-ref/networking/
> nova http://developer.openstack.org/api-ref/compute/
> sahara http://developer.openstack.org/api-ref/data-processing/
> senlin http://developer.openstack.org/api-ref/clustering/
> swift http://developer.openstack.org/api-ref/object-storage/
> zaqar http://developer.openstack.org/api-ref/messaging/
>
>
>
> These projects are using the in-tree workflow and common tools, but do not
> have a publish job in project-config in the jenkins/jobs/projects.yaml file.
>
>
>
> ceilometer
>
>
>
> --Projects not using common tooling--
>
> These projects have API docs but are not yet using the common tooling, as
> far as I can tell. Because of the user experience, I'm making a judgement
> call that these cannot be included in the common navigation. I have patched
> the projects.yaml file in the governance repo with the URLs I could
> screen-scrape, but if I'm incorrect please do patch the projects.yaml in
> the governance repo.
>
>
>
> astara
>
> cloudkitty
>
> congress
>
> magnum
>
> mistral
>
> monasca
>
> solum
>
> tacker
>
> trove
>
>
>
> Please reach out if you have questions or need assistance getting started
> with the new common tooling, documented here: http://docs.openstack.
> org/contributor-guide/api-guides.html.
>
>
>
> For search

Re: [openstack-dev] [OpenStack-docs] [neutron] [api] [doc] API reference for neutron stadium projects (re: API status report)

[Anne Gentle]

On Fri, Aug 12, 2016 at 3:29 AM, Akihiro Motoki <amot...@gmail.com> wrote:

> this mail focuses on neutron-specific topics. I dropped cinder and ironic
> tags.
>
> 2016-08-11 23:52 GMT+09:00 Anne Gentle <annegen...@justwriteclick.com>:
> >
> >
> > On Wed, Aug 10, 2016 at 2:49 PM, Anne Gentle <
> annegen...@justwriteclick.com>
> > wrote:
> >>
> >> Hi all,
> >> I wanted to report on status and answer any questions you all have about
> >> the API reference and guide publishing process.
> >>
> >> The expectation is that we provide all OpenStack API information on
> >> developer.openstack.org. In order to meet that goal, it's simplest for
> now
> >> to have all projects use the RST+YAML+openstackdocstheme+os-api-ref
> >> extension tooling so that users see available OpenStack APIs in a
> sidebar
> >> navigation drop-down list.
> >>
> >> --Migration--
> >> The current status for migration is that all WADL content is migrated
> >> except for trove. There is a patch in progress and I'm in contact with
> the
> >> team to assist in any way. https://review.openstack.org/#/c/316381/
> >>
> >> --Theme, extension, release requirements--
> >> The current status for the theme, navigation, and Sphinx extension
> tooling
> >> is contained in the latest post from Graham proposing a solution for the
> >> release number switchover and offers to help teams as needed:
> >> http://lists.openstack.org/pipermail/openstack-dev/2016-
> August/101112.html I
> >> hope to meet the requirements deadline to get those changes landed.
> >> Requirements freeze is Aug 29.
> >>
> >> --Project coverage--
> >> The current status for project coverage is that these projects are now
> >> using the RST+YAML in-tree workflow and tools and publishing to
> >> http://developer.openstack.org/api-ref/ so they will be
> >> included in the upcoming API navigation sidebar intended to span all
> >> OpenStack APIs:
> >>
> >> designate http://developer.openstack.org/api-ref/dns/
> >> glance http://developer.openstack.org/api-ref/image/
> >> heat http://developer.openstack.org/api-ref/orchestration/
> >> ironic http://developer.openstack.org/api-ref/baremetal/
> >> keystone http://developer.openstack.org/api-ref/identity/
> >> manila http://developer.openstack.org/api-ref/shared-file-systems/
> >> neutron-lib http://developer.openstack.org/api-ref/networking/
> >> nova http://developer.openstack.org/api-ref/compute/
> >> sahara http://developer.openstack.org/api-ref/data-processing/
> >> senlin http://developer.openstack.org/api-ref/clustering/
> >> swift http://developer.openstack.org/api-ref/object-storage/
> >> zaqar http://developer.openstack.org/api-ref/messaging/
> >>
> >> These projects are using the in-tree workflow and common tools, but do
> not
> >> have a publish job in project-config in the jenkins/jobs/projects.yaml
> file.
> >>
> >> ceilometer
> >
> >
> > Sorry, in reviewing further today I found another project that does not
> have
> > a publish job but has in-tree source files:
> >
> > cinder
> >
> > Team cinder: can you let me know where you are in your publishing comfort
> > level? Please add an api-ref-jobs: line with a target of block-storage to
> > jenkins/jobs/projects.yaml in the project-config repo to ensure
> publishing
> > is correct.
> >
> > Another issue is the name of the target directory for the final URL. Team
> > ironic can I change your api-ref-jobs: line to bare-metal instead of
> > baremetal? It'll be better for search engines and for alignment with the
> > other projects URLs: https://review.openstack.org/354135
> >
> > I've also uncovered a problem where a neutron project's API does not
> have an
> > official service name, and am working on a solution but need help from
> the
> > neutron team: https://review.openstack.org/#/c/351407
>
> I followed the discussion in https://review.openstack.org/#/c/351407
> and my understanding of the conclusion is to add API reference source
> of neutron stadium projects
> to neutron-lib and publish them under
> http://developer.openstack.org/api-ref/networking/ .
> I sounds reasonable to me.
>
> We can have a dedicated pages for each stadium project like networking-sfc
> like api-ref/networking/service-function-chaining.
> At now all APIs are placed under v2/ directory, but it is not good
> both from user and
> maintena

[openstack-dev] [cinder] [neutron] [ironic] [api] [doc] API status report

[Anne Gentle]

On Wed, Aug 10, 2016 at 2:49 PM, Anne Gentle <annegen...@justwriteclick.com>
wrote:

> Hi all,
> I wanted to report on status and answer any questions you all have about
> the API reference and guide publishing process.
>
> The expectation is that we provide all OpenStack API information on
> developer.openstack.org. In order to meet that goal, it's simplest for
> now to have all projects use the RST+YAML+openstackdocstheme+os-api-ref
> extension tooling so that users see available OpenStack APIs in a sidebar
> navigation drop-down list.
>
> --Migration--
> The current status for migration is that all WADL content is migrated
> except for trove. There is a patch in progress and I'm in contact with the
> team to assist in any way. https://review.openstack.org/#/c/316381/
>
> --Theme, extension, release requirements--
> The current status for the theme, navigation, and Sphinx extension tooling
> is contained in the latest post from Graham proposing a solution for the
> release number switchover and offers to help teams as needed:
> http://lists.openstack.org/pipermail/openstack-dev/2016-August/101112.html
> I hope to meet the requirements deadline to get those changes landed.
> Requirements freeze is Aug 29.
>
> --Project coverage--
> The current status for project coverage is that these projects are now
> using the RST+YAML in-tree workflow and tools and publishing to
> http://developer.openstack.org/api-ref/ so they will be
> included in the upcoming API navigation sidebar intended to span all
> OpenStack APIs:
>
> designate http://developer.openstack.org/api-ref/dns/
> glance http://developer.openstack.org/api-ref/image/
> heat http://developer.openstack.org/api-ref/orchestration/
> ironic http://developer.openstack.org/api-ref/baremetal/
> keystone http://developer.openstack.org/api-ref/identity/
> manila http://developer.openstack.org/api-ref/shared-file-systems/
> neutron-lib http://developer.openstack.org/api-ref/networking/
> nova http://developer.openstack.org/api-ref/compute/
> sahara http://developer.openstack.org/api-ref/data-processing/
> senlin http://developer.openstack.org/api-ref/clustering/
> swift http://developer.openstack.org/api-ref/object-storage/
> zaqar http://developer.openstack.org/api-ref/messaging/
>
> These projects are using the in-tree workflow and common tools, but do not
> have a publish job in project-config in the jenkins/jobs/projects.yaml file.
>
> ceilometer
>

Sorry, in reviewing further today I found another project that does not
have a publish job but has in-tree source files:

cinder

Team cinder: can you let me know where you are in your publishing comfort
level? Please add an api-ref-jobs: line with a target of block-storage
to jenkins/jobs/projects.yaml in the project-config repo to ensure
publishing is correct.

Another issue is the name of the target directory for the final URL. Team
ironic can I change your api-ref-jobs: line to bare-metal instead of
baremetal? It'll be better for search engines and for alignment with the
other projects URLs: https://review.openstack.org/354135

I've also uncovered a problem where a neutron project's API does not have
an official service name, and am working on a solution but need help from
the neutron team: https://review.openstack.org/#/c/351407
Thanks,
Anne


>
> --Projects not using common tooling--
> These projects have API docs but are not yet using the common tooling, as
> far as I can tell. Because of the user experience, I'm making a judgement
> call that these cannot be included in the common navigation. I have patched
> the projects.yaml file in the governance repo with the URLs I could
> screen-scrape, but if I'm incorrect please do patch the projects.yaml in
> the governance repo.
>
> astara
> cloudkitty
> congress
> magnum
> mistral
> monasca
> solum
> tacker
> trove
>
> Please reach out if you have questions or need assistance getting started
> with the new common tooling, documented here: http://docs.openstack.
> org/contributor-guide/api-guides.html.
>
> For searchlight, looking at http://developer.openstack.org/api-ref/search/
> they have the build job, but the info is not complete yet.
>
> One additional project I'm not sure what to do with is networking-nfc,
> since I'm not sure it is considered a neutron API. Can I get help to sort
> that question out?
>
> --Redirects from old pages--
> We have been adding .htaccess redirects from the old
> api-ref-servicename.html on developer.openstack.org as teams are
> comfortable with the accuracy of information and build stability. Please
> help out by patching the api-site repository's .htaccess file when you are
> ready to redirect. These projects could be ready for redirects but do not
> have them:
>

[openstack-dev] [api] [doc] API status report

[Anne Gentle]

Hi all,
I wanted to report on status and answer any questions you all have about
the API reference and guide publishing process.

The expectation is that we provide all OpenStack API information on
developer.openstack.org. In order to meet that goal, it's simplest for now
to have all projects use the RST+YAML+openstackdocstheme+os-api-ref
extension tooling so that users see available OpenStack APIs in a sidebar
navigation drop-down list.

--Migration--
The current status for migration is that all WADL content is migrated
except for trove. There is a patch in progress and I'm in contact with the
team to assist in any way. https://review.openstack.org/#/c/316381/

--Theme, extension, release requirements--
The current status for the theme, navigation, and Sphinx extension tooling
is contained in the latest post from Graham proposing a solution for the
release number switchover and offers to help teams as needed:
http://lists.openstack.org/pipermail/openstack-dev/2016-August/101112.html
I hope to meet the requirements deadline to get those changes landed.
Requirements freeze is Aug 29.

--Project coverage--
The current status for project coverage is that these projects are now
using the RST+YAML in-tree workflow and tools and publishing to
http://developer.openstack.org/api-ref/ so they will be
included in the upcoming API navigation sidebar intended to span all
OpenStack APIs:

designate http://developer.openstack.org/api-ref/dns/
glance http://developer.openstack.org/api-ref/image/
heat http://developer.openstack.org/api-ref/orchestration/
ironic http://developer.openstack.org/api-ref/baremetal/
keystone http://developer.openstack.org/api-ref/identity/
manila http://developer.openstack.org/api-ref/shared-file-systems/
neutron-lib http://developer.openstack.org/api-ref/networking/
nova http://developer.openstack.org/api-ref/compute/
sahara http://developer.openstack.org/api-ref/data-processing/
senlin http://developer.openstack.org/api-ref/clustering/
swift http://developer.openstack.org/api-ref/object-storage/
zaqar http://developer.openstack.org/api-ref/messaging/

These projects are using the in-tree workflow and common tools, but do not
have a publish job in project-config in the jenkins/jobs/projects.yaml file.

ceilometer

--Projects not using common tooling--
These projects have API docs but are not yet using the common tooling, as
far as I can tell. Because of the user experience, I'm making a judgement
call that these cannot be included in the common navigation. I have patched
the projects.yaml file in the governance repo with the URLs I could
screen-scrape, but if I'm incorrect please do patch the projects.yaml in
the governance repo.

astara
cloudkitty
congress
magnum
mistral
monasca
solum
tacker
trove

Please reach out if you have questions or need assistance getting started
with the new common tooling, documented here:
http://docs.openstack.org/contributor-guide/api-guides.html.

For searchlight, looking at http://developer.openstack.org/api-ref/search/
they have the build job, but the info is not complete yet.

One additional project I'm not sure what to do with is networking-nfc,
since I'm not sure it is considered a neutron API. Can I get help to sort
that question out?

--Redirects from old pages--
We have been adding .htaccess redirects from the old
api-ref-servicename.html on developer.openstack.org as teams are
comfortable with the accuracy of information and build stability. Please
help out by patching the api-site repository's .htaccess file when you are
ready to redirect. These projects could be ready for redirects but do not
have them:

designate
glance
heat
sahara
senlin
swift

I'm available for questions so please reach out as needed. I hope this
covers our current status.

A million thank yous to everyone who got us this far! Great teamwork, great
docs work, great UI work, and great API work everyone.
Anne

-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [OpenStack-docs] [glance] [docs] WADL migration achieved

[Anne Gentle]

Excellent! Thanks for sharing.

Well done, Brian, your efforts are much appreciated. Thanks Nikhil for
letting us celebrate with your team!

:) Happy to waddle-no-more.
Anne

On Sat, Jul 23, 2016 at 2:05 PM, Nikhil Komawar <nik.koma...@gmail.com> wrote:
> Hi all,
>
>
> I wanted to share my rejoice with you all that after persistent effort
> from Brian Rosmaita, we've (Glance) managed to accomplish another
> priority for this cycle the WADL migration, along with a good number of
> updates to the api-ref docs. For those unaware, this was the request
> from the docs team at the beginning of newton release [1].
>
>
> Kudos Brian and everyone else who have pitched into this effort
> including reviews. Please consider my congratulations to all involved
> for this nice change.
>
>
> [1]
> http://lists.openstack.org/pipermail/openstack-dev/2016-May/thread.html#93765
>
> --
>
> Thanks,
> Nikhil
>
>
> ___
> OpenStack-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs



-- 
Anne Gentle
www.justwriteclick.com

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

[openstack-dev] [api] testing openstackdocstheme and os-api-ref for API reference info

[Anne Gentle]

Hi -dev and -doc lists, and awesome devs Karen and Graham specifically -

I want to figure out the best way to coordinate a release of both the
theme and the sphinx extension so that we can test and publish and
iterate on the new API reference information display and navigation.

I think these patches are relevant and need to be merged:

openstackdocstheme
https://review.openstack.org/326668 (Actually include custom JS files)
https://review.openstack.org/329508 (API References dropdown menu)

os-api-ref
https://review.openstack.org/324805 (Tests for invalid parameter files)
https://review.openstack.org/327309 (microversion selector - dropdown)
https://review.openstack.org/318281 (HTTP Response Code Table)
https://review.openstack.org/#/c/322430/ (openstackdocstheme integration)

I think these patches are irrelevant or will keep us from the priority
task at hand, and it would be best not to merge them until we have
merged and then test these after getting the above patches released:
openstackdocstheme
https://review.openstack.org/269297 (Remove duplicate search field
from left sidebar)
https://review.openstack.org/339747 (Removed more reliance on CDNs)
https://review.openstack.org/333573 (Removed minimized files)
https://review.openstack.org/339314 (Fix the incorrect CSS values,
does something to headings I want more testing on)

I'm asking about timing and next steps. Are these the basic steps, and
am I missing any?

1. Review and merge the relevant patches in both os-api-ref and
openstackdocstheme.
2. Release new versions of  os-api-ref and openstackdocstheme.
3. Publish test content with the new versions.
4. Update relevant tox.ini and requirements.txt files.
5. Rebuild all api-ref source to implement the new navigation.

What I need to know:
Is there an order we should follow in merging so that testing across
browsers makes sense?

What is the scope of testing: is testing with the Compute content
enough or should we also test with Identity and other projects?

What timing should we attempt for steps 1 and 2 above? I'd like to aim
for August for 1 and 2, is that do-able?

Do we need to wait for all the migrated content to be ready for steps
4 and 5 above? I think the answer is no, but I might be missing
relevant info about how the navigation will work. I can also set up a
meeting for next week if that's easier than email, let me know.

Thanks,
Anne

-- 
Anne Gentle
www.justwriteclick.com

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

Re: [openstack-dev] [keystone][docs] API sprint results

[Anne Gentle]

Congrats to the team, what an effort! Thanks so much for putting this together.

Anne

On Fri, Jul 15, 2016 at 9:08 AM, Steve Martinelli
<s.martine...@gmail.com> wrote:
> First of all, thanks to everyone who participated, the API sprint was a huge
> success. We've converted nearly all of our old APIs (published on
> specs.openstack.org) over to the proper API site
> (http://developer.openstack.org/api-ref.html). We've got a few patches in
> flight, and a few TODOs that haven't begun yet, but things are looking
> positive. The end result of this is: we will no longer be publishing APIs to
> specs.openstack.org and we'll place our existing ones in an `attic` folder.
>
> By the numbers:
> - 10 unique patch authors
> - 40 patches merged
> - 8 patches in progress
>
> We used the `keystone-api-sprint` topic:
> https://review.openstack.org/#/q/topic:keystone-api-sprint
>
> Here's the etherpad we used, which contains more detail:
> https://etherpad.openstack.org/p/keystone-api-sprint
>
> Again, thanks to everyone who wrote and reviewed patches for this effort.
>
> stevemar
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
www.justwriteclick.com

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

Re: [openstack-dev] [magnum][lbaas][docs] Operator-facing installation guide

[Anne Gentle]

Let us know if this is what you're looking for:

http://docs.openstack.org/mitaka/networking-guide/adv-config-lbaas.html

Thanks Major Hayden for writing it up.
Anne

On Tue, Jun 14, 2016 at 3:54 PM, Hongbin Lu <hongbin...@huawei.com> wrote:

> Hi neutron-lbaas team,
>
> Could anyone confirm if there is an operator-facing install guide for
> neutron-lbaas. So far, the closest one we could find is:
> https://wiki.openstack.org/wiki/Neutron/LBaaS/HowToRun , which doesn't
> seem to be a comprehensive install guide. I asked that because there are
> several users who want to install Magnum but couldn't find an instruction
> to install neutron-lbaas. Although we are working on decoupling from
> neutron-lbaas, we still need to provide instruction for users who want a
> load balancer. If the install guide is missing, any plan to create one?
>
> Best regards,
> Hongbin
>
> > -Original Message-
> > From: Adrian Otto [mailto:adrian.o...@rackspace.com]
> > Sent: June-02-16 6:50 PM
> > To: OpenStack Development Mailing List (not for usage questions)
> > Subject: Re: [openstack-dev] [magnum][lbaas] Operator-facing
> > installation guide
> >
> > Brandon,
> >
> > Magnum uses neutron’s LBaaS service to allow for multi-master bays. We
> > can balance connections between multiple kubernetes masters, for
> > example. It’s not needed for single master bays, which are much more
> > common. We have a blueprint that is in design stage for de-coupling
> > magnum from neutron LBaaS for use cases that don’t require it:
> >
> > https://blueprints.launchpad.net/magnum/+spec/decouple-lbaas
> >
> > Adrian
> >
> > > On Jun 2, 2016, at 2:48 PM, Brandon Logan
> > <brandon.lo...@rackspace.com> wrote:
> > >
> > > Call me ignorance, but I'm surprised at neutron-lbaas being a
> > > dependency of magnum.  Why is this?  Sorry if it has been asked
> > before
> > > and I've just missed that answer?
> > >
> > > Thanks,
> > > Brandon
> > > On Wed, 2016-06-01 at 14:39 +, Hongbin Lu wrote:
> > >> Hi lbaas team,
> > >>
> > >>
> > >>
> > >> I wonder if there is an operator-facing installation guide for
> > >> neutron-lbaas. I asked that because Magnum is working on an
> > >> installation guide [1] and neutron-lbaas is a dependency of Magnum.
> > >> We want to link to an official lbaas guide so that our users will
> > >> have a completed instruction. Any pointer?
> > >>
> > >>
> > >>
> > >> [1] https://review.openstack.org/#/c/319399/
> > >>
> > >>
> > >>
> > >> Best regards,
> > >>
> > >> Hongbin
> > >>
> > >>
> > >>
> > _
> > >> _ OpenStack Development Mailing List (not for usage questions)
> > >> Unsubscribe:
> > >> openstack-dev-requ...@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-requ...@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-
> > requ...@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-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [api] [docs] Call for help: navigation for all API docs

[Anne Gentle]

Hi all,

Teams are making great progress in the source migration and the even newer
styling [1] is looking great!

What I'd like to ask for help on next is unifying navigation for the
content being published to developer.openstack.org/api-ref/ and
developer.openstack.org/api-guide/.

Previously, we had a sidebar for each service and version's API reference
document [2]. The sidebar is responsive, however, with the new Sphinx
sidebar, the service methods take over the sidebar. Also the prior sidebar
navigation was for reference information only.

The request is to provide a navigation that lets readers see all the
documented OpenStack APIs in a unified way. Perhaps an upper navigation
that can expand would be best. We do have the openstackdocstheme [3]
expanding sidebar menu with version info that perhaps can be reused.

Requirements based on our current tooling:
- Design should integrate well with our current theme, openstackdocstheme.
[3]
- Design should integrate well with the os-api-ref extensions. [4]
- Design should consider that some APIs have multiple versions.
- Both of the above are Sphinx-based and include jquery, bootstrap, and CSS
integration. Currently has Bootstrap v3.2.0 and JQuery 1.11.3 but these are
not required versions.
- Responsive design required; however mobile is 5% of traffic currently.
- Primary browsers are Chrome (60%), Firefox (26%), Safari and IE/Edge
(about 6% each).
- Should be able to add links to new API information through patchsets on
review.openstack.org.
- Should link to both API reference information and API tutorials and
guides.

If you're interested or have ideas, please write back to the openstack-dev
list.

Thanks,
Anne

1. https://api.os.gra.ham.ie/compute/ Thanks Graham Hayes!
2. http://developer.openstack.org/api-ref.html
3. https://github.com/openstack/openstackdocstheme
4. https://github.com/openstack/os-api-ref

-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [OpenStack-docs] What's Up, Doc? 20 May 2016

[Anne Gentle]

On Thu, May 19, 2016 at 11:48 PM, Lana Brindley <openst...@lanabrindley.com>
wrote:

> Hi everyone,
>
> I've been struck down by the dreaded flu this week, so it's been a bit
> quiet around here. I have, however, crawled out from under the tissues,
> throat lozenges, and episodes of Containment to pen my regular newsletter
> for you. See how dedicated I am to the cause? ;)
>
> The biggest updates this week have been on the API side of the ship, with
> the api-site bug list cleared out. Well done to Anne and Atsushi-san for
> the heavy lifting there.


All hail Atshushi for that herculean effort! He cleared over a hundred bugs
and asked great questions. Thank you so much Atsushi, I greatly appreciate
it.

Anne


> We also saw a lot of speciality team meetings kick off again this week,
> with more coming next week, so keep an eye on the mailing list and your
> ical for the projects you're interested in. We have also now hit our stride
> on the regular docs meetings, with the APAC meeting held this week, and the
> US one rolling around again next week. If you're a docs cross-project
> liaison, make sure you check out the timing and pick one that works for
> you, so we can make sure we're discussing *your* project.
>
> == Progress towards Newton ==
>
> 138 days to go!
>
> Bugs closed so far: 89
>
> Newton deliverables
> https://wiki.openstack.org/wiki/Documentation/NewtonDeliverables
> Feel free to add more detail and cross things off as they are achieved
> throughout the release. I will also do my best to ensure it's kept up to
> date for each newsletter.
>
> == Speciality Team Reports ==
>
> '''HA Guide: Bogdan Dobrelya'''
> No report this week.
>
> '''Install Guide: Lana Brindley'''
> Meetings start up next week:
> http://eavesdrop.openstack.org/#Documentation_Install_Team_Meeting
> Cookie cutter has been merged, repo here:
> http://git.openstack.org/cgit/openstack/installguide-cookiecutter/
> Need to merge spec: https://review.openstack.org/#/c/310588
>
> '''Networking Guide: Edgar Magana'''
> We have successfully changed the bi-weekly meeting schedule from odd to
> even weeks.
> There will not be meeting this week. Next meeting will be on June 2nd.
>
> '''Security Guide: Nathaniel Dillon'''
> No report this week.
>
> '''User Guides: Joseph Robinson'''
> Team Meeting restarted - Just me this week, I'll send a summary to the
> mailing list to keep everyone up to date, and if anyone is interested in
> joining in.
> Python SDK file moving - one item left from the Mitaka patch - Finding a
> location to move these files - dev and doc mailing list email forthcoming
> on where to put these files.
>
> '''Ops Guide: Shilla Saebi'''
> No report this week.
>
> '''API Guide: Anne Gentle'''
> The extension, os-api-ref, is now available via Pypi so that all projects
> can re-use it with test-requirements.txt. Thanks Sean Dague for this effort!
> Several projects have reviews in progress for their API reference
> conversion: glance https://review.openstack.org/#/c/312259/, manila
> https://review.openstack.org/#/c/313874, neutron
> https://review.openstack.org/#/c/314819, swift
> https://review.openstack.org/#/c/312315/,  trove
> https://review.openstack.org/#/c/316381. (There are probably more but
> those are on my radar).
> Please review the response code table at
> https://review.openstack.org/#/c/318281/ and
> http://i.imgur.com/onsRFtI.png for your use cases for API reference docs.
>
> '''Config/CLI Ref: Tomoyuki Kato'''
> No report this week.
>
> '''Training labs: Pranav Salunke, Roger Luethi'''
> No report this week.
>
> '''Training Guides: Matjaz Pancur'''
> Work on the slides for Training guides (
> https://review.openstack.org/#/c/295016/)
> Feedback about Upstream training in Austin (see
> http://eavesdrop.openstack.org/meetings/training_guides/2016/training_guides.2016-05-16-17.02.html
> )
>
> '''Hypervisor Tuning Guide: Blair Bethwaite
> Hi! I'm going to try looking after this for a while as Joe focuses on
> other things. Not promising much at this point beyond a little wiki
> gardening, but longer term I hope to align it with some activities in the
> scientific-wg (which I'm co-chairing with Stig Telfer), and it will
> probably become a point of reference for some of the activities we already
> have planned this cycle.
>
> '''UX/UI Guidelines: Michael Tullis, Stephen Ballard'''
> No report this week.
>
> == Site Stats ==
>
> While 90% of our readers have their browsers set to US English, just under
> 8% browse in Chinese, and a mere 0.15% use British English. That last one
> might be just me ;)
>
> == Doc team meeting ==
>
> Next meetings:
>
> The APAC meeting was

Re: [openstack-dev] [OpenStack-docs] [API] os-api-ref HTTP Response code formating

[Anne Gentle]

On Wed, May 18, 2016 at 1:42 PM, Hayes, Graham <graham.ha...@hpe.com> wrote:

> I was moving Designate to the os-api-ref extension, and I spotted
> something I thought we could do to improve the readability.
>

Thank you!


>
> Currently we have the HTTP Response Codes as a single
> line on the page - I thought a table might be handy as well.
>
> So, I had a go at it - and put up a POC[0]
>
> It outputs a table with the code and the project reason for the code[1]
>
> Example syntax is (used to generate [1]):
>
>  Response Codes
>  --
>
>  Normal
>  ^^
>
>  .. rest_response::
>
> - 200: OK
> - 100: Foo
> - 201: Zone Created
>
>
>
>  Error
>  ^
>
>  .. rest_response::
>
> - 405: Method *must* be POST
> - 403: Policy does not allow current user to create zone
> - 401: User must authenticate
> - 400: Supplied data is malformed.
> - 500: Something went wrong
>
> Is this something worth pursuing? Should it be laid out differently?
>

Definitely worth pursuing.

How will teams get to more definitively describe the responses? For
example, these descriptions for Compute errors:

The operation is not allowed because the corresponding
server is in a build state.

or

The operation is not allowed because the corresponding
server is being re-sized or backed up.

If those descriptions are embedded in the Sphinx extension, I think we'll
need to enable more detailed descriptions, and simply want to understand
how. When I looked at the code, that was my question in the review - help
me understand the mechanism better.

Thanks a bunch for doing this!
Anne



>
> Thanks,
>
> -- Graham
>
> 0 - https://review.openstack.org/#/c/318281/1
> 1 - http://i.imgur.com/onsRFtI.png
>
> ___
> OpenStack-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs] [api] Swagger limitations?

[Anne Gentle]

On Tue, May 17, 2016 at 9:51 AM, Jamie Hannaford <
jamie.hannaf...@rackspace.com> wrote:

> Hi Anne,
>
>
> So it seems that the only remaining issues are:
>
>
> - using $ref, which is not supported by some upstream tools
>
> - embedding Heat templates in a Swagger doc (not applicable to most
> OpenStack services)
>
>
> I responded to the other two in my e-mail to Sean. For the $ref problem,
> what is the problem with using NPM packages like swagger-tools or
> swagger-parser [1][2]? They can deference Swagger files into one unified
> file, which the build tool can then use for HTML rendering. The alternative
> is to let each project choose whether to use $ref or not. If they do want
> to spread Swagger docs out into separate documents and reference them, they
> will need to use a tool in whatever language that works.
>
>
>
It's not that these mechanisms are not supported. It's that we don't have
assigned development resources to work on Swagger/OpenAPI solutions.

In my first reply I sent you a link to an example using OpenStack
infrastructure already in place to use npm tooling to build. Please feel
free to test with that example: https://review.openstack.org/#/c/286659/

Anne


> I agree that Swagger is a new tool in a new ecosystem, but it definitely
> solves a lot of our use cases. I think it'd be a lot stronger if we adopted
> it - at least partially - and contributed our ideas for improvement back
> upstream.
>
>
> Was there any cons/disadvantages that I missed which would prevent is
> incorporating it?
>
>
> Jamie
>
>
> [1] https://www.npmjs.com/package/swagger-parser
>
> [2] https://github.com/jamiehannaford/swagger-magnum/blob/master/deref.js
>
>
> --
> *From:* Anne Gentle <annegen...@justwriteclick.com>
> *Sent:* 17 May 2016 15:35
> *To:* OpenStack Development Mailing List (not for usage questions)
> *Subject:* Re: [openstack-dev] [docs] [api] Swagger limitations?
>
>
>
> On Tue, May 17, 2016 at 7:57 AM, Jamie Hannaford <
> jamie.hannaf...@rackspace.com> wrote:
>
>> Hi all,
>>
>>
>> Back in March Anne wrote a great summary on the current state of Swagger
>> for OpenStack docs:
>> http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html.
>> <http://lists.openstack.org/pipermail/openstack-dev/2016-March/090659.html>
>>  Is this still the current state of things? Magnum is looking to
>> document its API soon, so I want to look at the feasibility of doing it in
>> Swagger. If it's not possible, RST should suffice.
>>
>>
>>
> Hi Jamie, thanks for asking. There are a few more limitations/concerns
> that I'll outline below.
>
>
>> In terms of the specific limitations that were listed:
>>
>>
>> - the /actions endpoint. Would it be possible to use vendor extensions to
>> solve this problem? For example, imagine that you want to document reboot
>> and rebuild operations. You could create custom verb properties for these
>> operations (`x-post-reboot`, `x-post-rebuild`) that would allow
>> differentiation of the JSON payload under the same URL category. The HTML
>> rendering would need to be adapted to take this into consideration. [1]
>>
>>
>> Yes, our first goal is to migrate off of WADL, but that won't prevent use
> of Swagger, it just means the first priority is to get all projects off of
> WADL.
>
> I think the details and nuances here were fairly well communicated in the
> rest of the thread [1] and in the etherpads, but of course that requires a
> LOT of reading. :)
>
> The main points I'd also like to ensure you know we discussed are [2]:
> 
> The current Plan of Record is to move to swagger. However this doesn't
> address a number of key issues:
> - swagger is young, most community tools around swagger are 50% - 80%
> solutions
> - swagger provides no facility for nova's 'action' interfaces or
> microversions
>
> NOTE: actions are used by nova, cinder, manilla, trove, neutron (in
> extensions) - so 40% of the 12 APIs documented on
> http://developer.openstack.org/ but only 5 of 19 (26%) REST APIs in
> OpenStack's governance
>
> NOTE: microversions are used by nova, manilla, ironic, and cinder (and
> neutron probably in the future unless it proves awful to document and use)
>
> NOTE: while Heat neither uses actions or microversions, it's content
> templates as inline post requests makes the swagger definition potentially
> really tough. Not that there shouldn't be full docs for those formats, but
> they just don't do that today. This same issue will hit other APIs that
> support post requests of 3rd party content format. Tacker

Re: [openstack-dev] [docs] [api] Swagger limitations?

[Anne Gentle]

; to a base resource would require fixing it in N copies of the file.
>
> If my understanding is correct, this would not happen. Each microversion,
> when released, is locked and would be preserved in that doc artefact. If a
> new software release is needed to fix a bug, that change would be
> encapsulated in a microversion with its own doc file.
>
> It would mean that users of your API must preselect the API version
> first before seeing anything. And they will only see a pristine document
> at that version.
>
> They will not have access to change notes inline (i.e. "New in 2.12").
> When looking at consuming an API. IMHO, that is something which is
> incredibly useful in reading an API. It's existence in the python
> standard lib makes it much clearer about whether you want to take
> advantage of feature X, or decide you'd rather have compatibility, and not.
>
> I definitely agree that this information is useful for the user, but I
> think it belongs in a RELEASENOTES format, not API docs. I think we should
> get to a position where API versioning is treated with the importance it
> deserves. The user should understand what version they want to interact
> with and make a decision, and then be presented with that API documentation.
>
> In terms of the logic of how we can re-use doc artefacts, we could do
> something like the following:
>
> * if a microversion which is selected by a user has a specific doc
> artefact, show it
> * if a specific microversion document does not exist, find its nearest
> sibling. For example, if no document was published for microversions 1.100
> or 1.99, but there was one published for 1.98, it is reasonable to assume
> that both 1.100 and 1.99 have the same API as 1.98, and can therefore use
> its doc artefact
>
> As with everything, it's trade offs, and what you want to get out of it.
>
> Swagger is a really interesting API Design Language. And if you start
> with Swagger when designing your API you impose a set of constraints
> that give you a bunch of benefits. If you go beyond it's constraints,
> you have imposed a very large and novel DSL on your environment (which
> is strictly no longer swagger), which means you get all the costs of
> conforming to an external standard without any of the benefits.
>
> I think that our actions interface turned out to be a mistake, but it's
> one made so long ago that it's pretty embedded. Long term getting
> ourselves out of that hole would be good.
>
> Completely agree. The good news is that the API-WG have a spec in review (
> https://review.openstack.org/#/c/234994/) which might solve these
> problems. They want to make actions first-class resources in the API. From
> my initial understanding, this could be represented in Swagger without the
> need for vendor extensions.
>

Sure, but the API WG is for new API designs.

This is the crux of the issue. For Magnum, you're probably fine with
Swagger/OpenAPI and we are not preventing you from working on it. For
existing APIs we have what we have and need to brutally prioritize in order
to meet user's needs for services that are already deployed and in use for
thousands of users.

Anne


>
> The microversions model is something that I think would be worth
> engaging the OpenAPI upstream community. Our current implementation is
> pretty OpenStack specific, but the concept would apply to any open
> source project with a REST API that is CDed at different rates by
> different deployers.
>
> -Sean
>
> --
> Sean Dague
> http://dague.net
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
> 
> Rackspace International GmbH a company registered in the Canton of Zurich,
> Switzerland (company identification number CH-020.4.047.077-1) whose
> registered office is at Pfingstweidstrasse 60, 8005 Zurich, Switzerland.
> Rackspace International GmbH privacy policy can be viewed at
> www.rackspace.co.uk/legal/swiss-privacy-policy - This e-mail message may
> contain confidential or privileged information intended for the recipient.
> Any dissemination, distribution or copying of the enclosed material is
> prohibited. If you receive this transmission in error, please notify us
> immediately by e-mail at ab...@rackspace.com and delete the original
> message. Your cooperation is appreciated.
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs] [api] Swagger limitations?

[Anne Gentle]

 Zurich, Switzerland.
> Rackspace International GmbH privacy policy can be viewed at
> www.rackspace.co.uk/legal/swiss-privacy-policy - This e-mail message may
> contain confidential or privileged information intended for the recipient.
> Any dissemination, distribution or copying of the enclosed material is
> prohibited. If you receive this transmission in error, please notify us
> immediately by e-mail at ab...@rackspace.com and delete the original
> message. Your cooperation is appreciated.
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] [senlin] [keystone] [ceilometer] [telemetry] Questions about api-ref launchpad bugs

[Anne Gentle]

On Mon, May 16, 2016 at 8:04 AM, Atsushi SAKAI <sak...@jp.fujitsu.com>
wrote:

> Anne
>
> I move and clean up api-site issues as far as I can do.
>   But it still remain 36 open bugs.
>   mainly  WADL, INCOMPLETE status, FIX COMMITED status,
>   and too many project issue (like 1390528, 1390523 etc)
>   Would you check it?
>
>
Thanks! I'm going through a clean up round myself, some are
openstack-doc-tools. Some I'd consider "Fix Released" so I'm commenting
when I change the status.

Thank you so much for going through these. Great work -- and great numbers.
Now the bugs in openstack-api-site are either for API Quick Start or the
First App on OpenStack content.

Anne



> Thanks
> Atsushi SAKAI
>
> On Wed, 11 May 2016 10:04:06 -0500
> Anne Gentle <annegen...@justwriteclick.com> wrote:
>
> > On Wed, May 11, 2016 at 8:12 AM, Atsushi SAKAI <sak...@jp.fujitsu.com>
> > wrote:
> >
> > > Anne
> > > Augustina
> > >
> > >   Thank you for description and help.
> > >
> > >   I will clean up launchpad api-site within this week at first.
> > >   Since just around 150 issues and many issues are tagged it already.
> > >   I can manually move most of the issues.
> > >   Does any problem exist for this method?
> > >
> > >
> > Sounds good to me. I hadn't found a script, so a manual move is fine, and
> > if you're able then please go for it. :)
> >
> >
> > >   Then I will do it for remaining api-ref migration issues.
> > >
> >
> > Sounds good. For any tooling issues, use the
> > https://bugs.launchpad.net/openstack-doc-tools tracker.
> >
> > Thanks!
> > Anne
> >
> >
> > >
> > > Thanks
> > > Atsushi SAKAI
> > >
> > >
> > >
> > >
> > >
> > > On Tue, 10 May 2016 07:53:19 -0500
> > > Anne Gentle <annegen...@justwriteclick.com> wrote:
> > >
> > > > Great questions, so I'm copying the -docs and -dev lists to make sure
> > > > people know the answers.
> > > >
> > > > On Tue, May 10, 2016 at 5:14 AM, Atsushi SAKAI <
> sak...@jp.fujitsu.com>
> > > > wrote:
> > > >
> > > > > Hello Anne
> > > > >
> > > > >   I have several question when I am reading through etherpad's (in
> > > > > progress).
> > > > >   It would be appreciated to answer these questions.
> > > > >
> > > > > 1)Should api-ref launchpad **bugs** be moved to each modules
> > > > >   (like keystone, nova etc)?
> > > > >   Also, this should be applied to moved one's only or all
> components?
> > > > >(compute, baremetal Ref.2)
> > > > >
> > > > >   Ref.
> > > > > https://etherpad.openstack.org/p/austin-docs-newtonplan
> > > > > API site bug list cleanup: move specific service API ref bugs
> to
> > > > > project's Launchpad
> > > > >
> > > > >   Ref.2
> > > > > http://developer.openstack.org/api-ref/compute/
> > > > > http://developer.openstack.org/api-ref/baremetal/
> > > >
> > > >
> > > > Yes! I definitely got agreement from nova team that they want them.
> Does
> > > > anyone have a Launchpad script that could help with the bulk
> > > filter/export?
> > > > Also, are any teams concerned about taking on their API reference
> bugs?
> > > > Let's chat.
> > > >
> > > >
> > > > >
> > > > >
> > > > > 2)Status of API-Ref
> > > > >   a)Why keystone and senlin are no person at this moment?
> > > > >
> > > > >
> > > > >
> > > > Keystone -- after the Summit, keystone had someone sign up [1], but
> > > sounds
> > > > like we need someone else. Brant, can you help us find someone?
> > > >
> > > > Senlin -- Qiming Teng had asked a lot of questions earlier in the
> process
> > > > and tested the instructions. Qiming had good concerns about personal
> > > > bandwidth limits following along with all the changes. Now that it's
> > > > settled, I'll follow up (and hoping the senlin team is reading the
> list).
> > > >
> > > >
> > > > >   b)What is your plan for sahara and ceilometer?
> > > > >  (It seems already exist the document.)
> > 

Re: [openstack-dev] [api] [senlin] [keystone] [ceilometer] [telemetry] Questions about api-ref launchpad bugs

[Anne Gentle]

On Wed, May 11, 2016 at 8:12 AM, Atsushi SAKAI <sak...@jp.fujitsu.com>
wrote:

> Anne
> Augustina
>
>   Thank you for description and help.
>
>   I will clean up launchpad api-site within this week at first.
>   Since just around 150 issues and many issues are tagged it already.
>   I can manually move most of the issues.
>   Does any problem exist for this method?
>
>
Sounds good to me. I hadn't found a script, so a manual move is fine, and
if you're able then please go for it. :)


>   Then I will do it for remaining api-ref migration issues.
>

Sounds good. For any tooling issues, use the
https://bugs.launchpad.net/openstack-doc-tools tracker.

Thanks!
Anne


>
> Thanks
> Atsushi SAKAI
>
>
>
>
>
> On Tue, 10 May 2016 07:53:19 -0500
> Anne Gentle <annegen...@justwriteclick.com> wrote:
>
> > Great questions, so I'm copying the -docs and -dev lists to make sure
> > people know the answers.
> >
> > On Tue, May 10, 2016 at 5:14 AM, Atsushi SAKAI <sak...@jp.fujitsu.com>
> > wrote:
> >
> > > Hello Anne
> > >
> > >   I have several question when I am reading through etherpad's (in
> > > progress).
> > >   It would be appreciated to answer these questions.
> > >
> > > 1)Should api-ref launchpad **bugs** be moved to each modules
> > >   (like keystone, nova etc)?
> > >   Also, this should be applied to moved one's only or all components?
> > >(compute, baremetal Ref.2)
> > >
> > >   Ref.
> > > https://etherpad.openstack.org/p/austin-docs-newtonplan
> > > API site bug list cleanup: move specific service API ref bugs to
> > > project's Launchpad
> > >
> > >   Ref.2
> > > http://developer.openstack.org/api-ref/compute/
> > > http://developer.openstack.org/api-ref/baremetal/
> >
> >
> > Yes! I definitely got agreement from nova team that they want them. Does
> > anyone have a Launchpad script that could help with the bulk
> filter/export?
> > Also, are any teams concerned about taking on their API reference bugs?
> > Let's chat.
> >
> >
> > >
> > >
> > > 2)Status of API-Ref
> > >   a)Why keystone and senlin are no person at this moment?
> > >
> > >
> > >
> > Keystone -- after the Summit, keystone had someone sign up [1], but
> sounds
> > like we need someone else. Brant, can you help us find someone?
> >
> > Senlin -- Qiming Teng had asked a lot of questions earlier in the process
> > and tested the instructions. Qiming had good concerns about personal
> > bandwidth limits following along with all the changes. Now that it's
> > settled, I'll follow up (and hoping the senlin team is reading the list).
> >
> >
> > >   b)What is your plan for sahara and ceilometer?
> > >  (It seems already exist the document.)
> > >
> >
> > Yes, these are two I had seen already have RST, but they do not use the
> > helpful Sphinx extensions.
> >
> > Sahara -- Mike McCune, we should chat about the plans. Are you okay with
> > moving towards the common framework and editing the current RST files to
> > use the rest_method and rest_parameters Sphinx directives?
> >
> > Ceilometer -- sorry, Julien, I hadn't reached out individually to you.
> > Could you let me know your plans for the RST API reference docs?
> >
> >
> > >   c)When is the table's status changed to "Done"?
> > >  nova (compute) and ironic (baremetal) seems first patch merged
> > >  and see the document already.
> > >
> >
> > I'll change those two to Done.
> >
> > Thanks for asking -
> > Anne
> >
> >
> > >
> > >
> > >   Ref.
> > > [1]
> > >
> https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan
> > >
> > >
> > > Thanks
> > >
> > > Atsushi SAKAI
> > >
> >
> >
> >
> > --
> > Anne Gentle
> > www.justwriteclick.com
>
>
> --
> Atsushi SAKAI <sak...@jp.fujitsu.com>
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] [senlin] [keystone] [ceilometer] [telemetry] Questions about api-ref launchpad bugs

[Anne Gentle]

On Tue, May 10, 2016 at 8:12 AM, Julien Danjou <jul...@danjou.info> wrote:

> On Tue, May 10 2016, Anne Gentle wrote:
>
> > Ceilometer -- sorry, Julien, I hadn't reached out individually to you.
> > Could you let me know your plans for the RST API reference docs?
>
> For Gnocchi and Aodh, we want to move to whatever the new format is and
> build a reference description in our tree (so we can maintain and update
> it as we go). I heard Swagger is the way to go, so that's we're going to
> look into – unless someone redirects us.
>

I won't redirect you, just guide. :) To get Swagger to build to HTML you'll
need something like this patch we experimented with in api-site:
https://review.openstack.org/#/c/286659/ Or, simply provide the Swagger
files and let users do with them as they want. See our talk at the Summit
for some ideas:
https://www.openstack.org/videos/video/openapi-as-a-standard-a-new-way-forward-for-api-documentation-design-and-tool


>
> For examples of usage of our APIs, we have a documentation built
> dynamically within the documentation for Gnocchi (see
> http://gnocchi.xyz/rest.html). Real HTTP calls are being made to
> generate that documentation, so no replies are hand written. That makes
> us sure that the documentation is always up-to-date.
> We may want to also implement that in Aodh at some point.
>
> For Ceilometer, I don't think we want to put much effort in it. The v2
> API is being deprecated and slowly moved out of our way. The /v2/events
> API is being moved in a 4th project, named Panko, that will follow
> Gnocchi & Aodh in term of documentation.
>

It's a small set of files:
https://github.com/openstack/api-site/tree/master/api-ref/source/telemetry/v2
How about I ask someone to do the conversion and add it to
https://github.com/openstack/ceilometer? I have someone in mind who's
looking for a task. Let me know and I'll get her started.

Thanks,
Anne


>
> I hope that'll clarify things!
>
> Cheers,
> --
> Julien Danjou
> ;; Free Software hacker
> ;; https://julien.danjou.info
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] summit session recap - getting API Docs off WADL and into RST

[Anne Gentle]

All docs are migrated off of WADL now, but not all are publishing. Please
see https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan
and my post that high-fived with Sean's just minutes ago for the latest
status.

http://lists.openstack.org/pipermail/openstack-dev/2016-May/094478.html

On Tue, May 10, 2016 at 7:21 AM, Sean Dague <s...@dague.net> wrote:

> Part of the cross project session track -
> https://etherpad.openstack.org/p/newton-api-docs-rst
>
> The first half of the session was spent going over the background issues
> and the work so far. The TL;DR
>
> * We need to get off WADL, it's a dead spec, and it's use is inhibiting
> contributions
> * We *need* to get up to date docs to our users, ASAP. The API
> References are way out of data and inaccurate in most places (and
> missing entirely for 50% of our projects with REST APIs)
> * Swagger (OpenAPI) was looked at, but there are hard problems in our
> legacy APIs that aren't possible to solve within the spec at hand
> * Nova team started building some semistructured tooling based on RST /
> Sphinx to move forward.
>
> We then looked at the sphinx extension work in the Nova api-ref tree.
>
> Question: why not https://pythonhosted.org/sphinxcontrib-httpdomain/?
> Answer: we have some specific needs on formating, headers where it
> doesn't fit (see etherpad for full answer).
>
> Next Steps:
>
> * Nova team is doing a doc sprint to try to get through verification of
> the content we've got
> * Once that is done (under control) sdague to work on splitting out
> sphinx extension into a dedicated project to make it easy for others to
> consume / contribute
> * Cinder, Ironic, and Keystone ready to get started on similar conversion
>
> --
> Sean Dague
> http://dague.net
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [api] [senlin] [keystone] [ceilometer] [telemetry] Questions about api-ref launchpad bugs

[Anne Gentle]

Great questions, so I'm copying the -docs and -dev lists to make sure
people know the answers.

On Tue, May 10, 2016 at 5:14 AM, Atsushi SAKAI <sak...@jp.fujitsu.com>
wrote:

> Hello Anne
>
>   I have several question when I am reading through etherpad's (in
> progress).
>   It would be appreciated to answer these questions.
>
> 1)Should api-ref launchpad **bugs** be moved to each modules
>   (like keystone, nova etc)?
>   Also, this should be applied to moved one's only or all components?
>(compute, baremetal Ref.2)
>
>   Ref.
> https://etherpad.openstack.org/p/austin-docs-newtonplan
> API site bug list cleanup: move specific service API ref bugs to
> project's Launchpad
>
>   Ref.2
> http://developer.openstack.org/api-ref/compute/
> http://developer.openstack.org/api-ref/baremetal/


Yes! I definitely got agreement from nova team that they want them. Does
anyone have a Launchpad script that could help with the bulk filter/export?
Also, are any teams concerned about taking on their API reference bugs?
Let's chat.


>
>
> 2)Status of API-Ref
>   a)Why keystone and senlin are no person at this moment?
>
>
>
Keystone -- after the Summit, keystone had someone sign up [1], but sounds
like we need someone else. Brant, can you help us find someone?

Senlin -- Qiming Teng had asked a lot of questions earlier in the process
and tested the instructions. Qiming had good concerns about personal
bandwidth limits following along with all the changes. Now that it's
settled, I'll follow up (and hoping the senlin team is reading the list).


>   b)What is your plan for sahara and ceilometer?
>  (It seems already exist the document.)
>

Yes, these are two I had seen already have RST, but they do not use the
helpful Sphinx extensions.

Sahara -- Mike McCune, we should chat about the plans. Are you okay with
moving towards the common framework and editing the current RST files to
use the rest_method and rest_parameters Sphinx directives?

Ceilometer -- sorry, Julien, I hadn't reached out individually to you.
Could you let me know your plans for the RST API reference docs?


>   c)When is the table's status changed to "Done"?
>  nova (compute) and ironic (baremetal) seems first patch merged
>  and see the document already.
>

I'll change those two to Done.

Thanks for asking -
Anne


>
>
>   Ref.
> [1]
> https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan
>
>
> Thanks
>
> Atsushi SAKAI
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [OpenStack-docs] What's Up, Doc? 6 May 2016

[Anne Gentle]

On Sat, May 7, 2016 at 1:51 PM, Andreas Jaeger <a...@suse.com> wrote:

> On 05/07/2016 06:09 PM, Ildikó Váncsa wrote:
> > Hi Matt,
> >
> > I'm open to discuss what would be the best way forward in this topic.
> First of all I would like to understand the intention with document
> structures long term to see how we can have a scalable and maintainable
> process.
> >
> > My experience is that keeping the documentation up to date separately
> from the code can be difficult that results in outdated materials, which
> also leads to bad user experience and impression.
> >
> > Would this topic be sufficient for one of the team meetings?
>
> Right now we have the Install Guide as first guide where we move content
> to the teams and still want to provide this from one place.
>
> I suggest that we do the Install Guide first and then consider whether
> that is a model that we should use for other documents as well,
>

Another example model to keep an eye on is the current move of content from
api-site to project repos. Let's see how that goes as well --
quality/accuracy, usefulness, and ongoing maintenance as first goals.

Anne


>
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: 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-docs mailing list
> openstack-d...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [api] [docs] [cinder] [swift] [glance] [keystone] [ironic] [trove] [neutron] [heat] [senlin] [manila] [sahara] RST + YAML files ready for pick up from WADL migration

[Anne Gentle]

On Tue, May 3, 2016 at 8:39 AM, Sheel Rana Insaan <ranasheel2...@gmail.com>
wrote:

> Hi Anne,
>
> Sure, I will pick for cinder.
>
> Thanks!!
>
>
Thank you! I added your name to the wiki page:

https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan

Meant to add that to my email -- if you are interested in working on the
migration for a service, please add your name to the wiki page.

Thanks,
Anne


> Best Regards,
> Sheel Rana
>
> On Tue, May 3, 2016 at 6:59 PM, Anne Gentle <annegen...@justwriteclick.com
> > wrote:
>
>> Hi all,
>> This patch contains all the RST + YAML for projects to bring over to
>> their repos to begin building API reference information from within your
>> repo. Get a copy of this patch, and pick up the files for your service in
>> api-site/api-ref/source/:
>>
>> https://review.openstack.org/#/c/311596/
>>
>> There is required cleanup, and you'll need an index.rst, conf.py, and
>> build jobs. All of these can be patterned after the nova repository api-ref
>> directory. Read more at
>> http://docs.openstack.org/contributor-guide/api-guides.html
>>
>> It's overall in good shape thanks to Karen Bradshaw, Auggy Ragwitz,
>> Andreas Jaeger, and Sean Dague. Appreciate the help over the finish line
>> during Summit week, y'all.
>>
>> The api-site/api-ref files are now frozen and we will not accept patches.
>> The output at developer.openstack.org/api-ref.html remains frozen until
>> we can provide redirects to the newly-sourced-and-built files. Please, make
>> this work a priority in this release. Ideally we can get everyone ready by
>> Milestone 1 (May 31).
>>
>> If you would like to use a Swagger/OpenAPI file, pick that file up from
>> developer.openstack.org/draft/swagger/ and create build jobs from your
>> repo to publish it on developer.openstack.org.
>>
>> Let me know if you have questions.
>> Thanks,
>> Anne
>>
>> --
>> Anne Gentle
>> www.justwriteclick.com
>>
>> __
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe:
>> openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [api] [docs] [cinder] [swift] [glance] [keystone] [ironic] [trove] [neutron] [heat] [senlin] [manila] [sahara] RST + YAML files ready for pick up from WADL migration

[Anne Gentle]

Hi all,
This patch contains all the RST + YAML for projects to bring over to their
repos to begin building API reference information from within your repo.
Get a copy of this patch, and pick up the files for your service in
api-site/api-ref/source/:

https://review.openstack.org/#/c/311596/

There is required cleanup, and you'll need an index.rst, conf.py, and build
jobs. All of these can be patterned after the nova repository api-ref
directory. Read more at
http://docs.openstack.org/contributor-guide/api-guides.html

It's overall in good shape thanks to Karen Bradshaw, Auggy Ragwitz, Andreas
Jaeger, and Sean Dague. Appreciate the help over the finish line during
Summit week, y'all.

The api-site/api-ref files are now frozen and we will not accept patches.
The output at developer.openstack.org/api-ref.html remains frozen until we
can provide redirects to the newly-sourced-and-built files. Please, make
this work a priority in this release. Ideally we can get everyone ready by
Milestone 1 (May 31).

If you would like to use a Swagger/OpenAPI file, pick that file up from
developer.openstack.org/draft/swagger/ and create build jobs from your repo
to publish it on developer.openstack.org.

Let me know if you have questions.
Thanks,
Anne

-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [api] [docs] WADL migration sign-up

[Anne Gentle]

Hi all,
Thanks to all those who groaned with me through the API docs working
session. :) I patched the instructions:
https://review.openstack.org/#/c/310514/

As promised, I've created this wiki page for people to sign up for a
migration task:

https://wiki.openstack.org/wiki/Documentation/Migrate#API_Reference_Plan

I've subscribed to changes on the page so I can keep track of who wants to
work on which services. Thanks so much!

Anne

-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Doc] place to add API reference

[Anne Gentle]

On Fri, Apr 15, 2016 at 12:04 PM, Sean McGinnis <sean.mcgin...@gmx.com>
wrote:

> On Fri, Apr 15, 2016 at 11:17:40AM -0500, Anne Gentle wrote:
> > Sean and I are collaborating on a cross project spec to talk about at
> the Summit. Can you talk about concerns or cons to this approach so we can
> put it in the spec?
> >
> > Thanks,
> > Anne
>
> Thanks Anne. No concerns at the moment. I was just afraid I had missed
> something from the discussions.
>

Okay, good. My sense is that this project ownership of API docs is a great
direction.


>
> Thanks for the clarification. I will watch for the cross project
> session.
>

Here's the one you want.

https://www.openstack.org/summit/austin-2016/summit-schedule/events/9479

Thanks -
Anne


>
> Thanks!
> Sean
>
> >
> >
> > > On Apr 15, 2016, at 11:02 AM, Sean McGinnis <sean.mcgin...@gmx.com>
> wrote:
> > >
> > >> On Fri, Apr 15, 2016 at 09:38:20AM +0200, Andreas Jaeger wrote:
> > >>> On 04/15/2016 08:14 AM, Masahito MUROI wrote:
> > >>> Hi Doc team folks,
> > >>>
> > >>> Congress team plans to add API reference into [1] instead of [2] to
> > >>> follow official documentation project. But I found the design session
> > >>> about a API docs style[3].
> > >>>
> > >>> For now, is it ok to add API reference [1], or should we wait the
> > >>> decision about style of API reference repository?
> > >>>
> > >>> 1. http://developer.openstack.org/api-ref.html
> > >>> 2. http://docs.openstack.org/developer/congress/
> > >>> 3.
> > >>>
> https://www.openstack.org/summit/austin-2016/summit-schedule/events/9479?goback=1
> > >>
> > >>
> > >> See the work that is done by Sean Dague and Anne Gentle for nova and
> > >> follow this setup:
> > >>
> http://lists.openstack.org/pipermail/openstack-dev/2016-April/092234.html
> > >
> > > I thought I followed all of the emails on moving to Swagger then RST.
> > > Moving the api docs in tree with the projects is something I wasn't
> > > aware of.
> > >
> > > Was there a cross-project spec for this or something detailing the long
> > > term goal and direction each team should take for doing this? I see the
> > > work Nova has done (looks great) but is that something that team has
> > > decided to explore or is this something all of us should be involved
> in?
> > >
> > > Sorry, just caught a little off guard here and trying to figure out
> what
> > > I've missed.
> > >
> > > Sean
> > >
> > >>
> > >> There have been a couple more emails in the last months on this topic
> > >>
> > >> Also, there's a spec:
> > >>
> http://specs.openstack.org/openstack/docs-specs/specs/mitaka/app-guides-mitaka-vision.html
> > >>
> > >> so, you should do this in your own repository, set up proper jobs -
> > >> and then publish to developer.openstack.org
> > >
> > > That spec doesn't say anything about moving to each project's
> > > repository. Is there something else with more detail?
> > >
> > >>
> > >> Andreas
> > >> --
> > >> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica:
> 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:
> openstack-dev-requ...@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-requ...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Doc] place to add API reference

[Anne Gentle]

Sean and I are collaborating on a cross project spec to talk about at the 
Summit. Can you talk about concerns or cons to this approach so we can put it 
in the spec?

Thanks,
Anne


> On Apr 15, 2016, at 11:02 AM, Sean McGinnis <sean.mcgin...@gmx.com> wrote:
> 
>> On Fri, Apr 15, 2016 at 09:38:20AM +0200, Andreas Jaeger wrote:
>>> On 04/15/2016 08:14 AM, Masahito MUROI wrote:
>>> Hi Doc team folks,
>>> 
>>> Congress team plans to add API reference into [1] instead of [2] to
>>> follow official documentation project. But I found the design session
>>> about a API docs style[3].
>>> 
>>> For now, is it ok to add API reference [1], or should we wait the
>>> decision about style of API reference repository?
>>> 
>>> 1. http://developer.openstack.org/api-ref.html
>>> 2. http://docs.openstack.org/developer/congress/
>>> 3.
>>> https://www.openstack.org/summit/austin-2016/summit-schedule/events/9479?goback=1
>> 
>> 
>> See the work that is done by Sean Dague and Anne Gentle for nova and
>> follow this setup:
>> http://lists.openstack.org/pipermail/openstack-dev/2016-April/092234.html
> 
> I thought I followed all of the emails on moving to Swagger then RST.
> Moving the api docs in tree with the projects is something I wasn't
> aware of.
> 
> Was there a cross-project spec for this or something detailing the long
> term goal and direction each team should take for doing this? I see the
> work Nova has done (looks great) but is that something that team has
> decided to explore or is this something all of us should be involved in?
> 
> Sorry, just caught a little off guard here and trying to figure out what
> I've missed.
> 
> Sean
> 
>> 
>> There have been a couple more emails in the last months on this topic
>> 
>> Also, there's a spec:
>> http://specs.openstack.org/openstack/docs-specs/specs/mitaka/app-guides-mitaka-vision.html
>> 
>> so, you should do this in your own repository, set up proper jobs -
>> and then publish to developer.openstack.org
> 
> That spec doesn't say anything about moving to each project's
> repository. Is there something else with more detail?
> 
>> 
>> Andreas
>> -- 
>> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: 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: openstack-dev-requ...@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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Doc] place to add API reference

[Anne Gentle]

On Fri, Apr 15, 2016 at 1:14 AM, Masahito MUROI <
muroi.masah...@lab.ntt.co.jp> wrote:

> Hi Doc team folks,
>
> Congress team plans to add API reference into [1] instead of [2] to
> follow official documentation project. But I found the design session
> about a API docs style[3].
>
> For now, is it ok to add API reference [1], or should we wait the
> decision about style of API reference repository?
>

Thanks for asking! The nova proof-of-concept is now publishing here as of
yesterday:
http://developer.openstack.org/api-ref/compute/

I'm working on updating the instructions here:
http://docs.openstack.org/contributor-guide/api-guides.html

With more updates now: https://review.openstack.org/#/c/306076/

Appreciate you reaching out to the list. And thanks Andreas for keeping up
too. :)

Anne


>
> 1. http://developer.openstack.org/api-ref.html
> 2. http://docs.openstack.org/developer/congress/
> 3.
>
> https://www.openstack.org/summit/austin-2016/summit-schedule/events/9479?goback=1
>
> best regard,
> Masahito
>
> --
> 室井 雅仁(Masahito MUROI)
> Software Innovation Center, NTT
> Tel: +81-422-59-4539
>
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Constant attempts from Matthew Kassawara to remove Debian from the install-guide

[Anne Gentle]

Okay. I'll try to propose an idea.

In the Mitaka install spec review, [1] I asked if the drama was worth the
extra effort to remove. Personally I don't believe so, having refereed this
discussion for years now.

I think you're both reasonable people and do believe in OpenStack. You both
want it to succeed, yet for the particular goals of the install guide you
haven't come to consensus. That's fine.

I have another idea for a way forward that doesn't require consensus across
teams. Now that we have the governance in place for debian packaging, let's
move the debian install guide to a new repo that can go under the packaging
project, and you can create and maintain build jobs for the debian install
guide. No one will have the additional burden of maintaining conditional
text. You can write what you like and publish what you want, taking
responsibility for quality control and ongoing maintenance.

Monty's the PTL for packaging-rpm. [2] Can you envision a
debian-install-guide repo within the packaging-rpm team, with both a review
team and bug triaging only for that repo? You'll need to work on the gate
and build jobs as well, but I truly believe we have the systems in place to
enable this. And with the direction of the individual projects taking
responsibility for their install guides, we have a framework we're moving
towards and this case seems to fit the new framework. [3]

I think it's a great use of the time you have now, and lets us all stop
losing time to the debate.

Thoughts?
Anne

1.
https://review.openstack.org/#/c/274231/4/specs/mitaka/installguide-mitaka.rst
2.
http://git.openstack.org/cgit/openstack/election/plain//candidates/newton/Packaging-Deb/Monty_Taylor.txt
3. https://review.openstack.org/#/c/301284/


On Fri, Apr 8, 2016 at 11:47 AM, Thomas Goirand <z...@debian.org> wrote:

> I don't do ab-dominem pointing fingers. I believe this is normally
> detrimental to the project. However, I don't have any choice in this
> case. Matthew is consistently attempting to remove the Debian support
> from the install-guide. He's doing it again:
>
> https://review.openstack.org/#/c/302934/
>
> And without any discussion with me, who did all of the work. And again,
> just after the release, which is when I usually have the time to work
> again on the install-guide.
>
> The first time it happened, was when the install-guide was converted to
> RST. I was told I couldn't commit, as it was frozen.
>
> This type of behavior is completely in opposition to what we've voted
> for: the bit tent, where everyone is welcome. In this case Matthew, is
> clearly making a war against Debian support in the install-guide. I
> don't want this to happen.
>
> Matthew, in his CR, wrote:
> "lack of maintenance and usability"
>
> Well, first of all, I don't agree with that. Second, like on every
> releases, I intended to work on it after the packages were done, for the
> Mitaka release.
>
> Another thing is that the Debian packages are the only ones available
> for many services, as Canonical doesn't work on them (these packages are
> just sync from Debian, at best). So we'd be effectively removing the
> only OS where it can be installed.
>
> I received *many* feedback from people who would like to see more of
> Debian in the install-guide, not less, and even less get it completely
> removed. During a year, I had to point to the direct link where the
> Debian guide was installed, as the link on docs.openstack.org was
> removed (up to now, still don't understand why this happened). Now, even
> the generation of the Debian docs is removed, and I can't point to it.
>
> This has to stop. This is disgusting, and with no valid reason. The same
> way every project should be welcome in the install-guide, contributors
> should be welcome, and for all operating systems.
>
> Cheers,
>
> Thomas Goirand (zigo)
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs] [api] Oh Swagger, where art thou?

[Anne Gentle]

On Thu, Mar 31, 2016 at 11:22 AM, Jim Rollenhagen <j...@jimrollenhagen.com>
wrote:

> On Thu, Mar 31, 2016 at 09:50:48AM -0400, Sean Dague wrote:
> > On 03/31/2016 09:43 AM, Jim Rollenhagen wrote:
> > > On Thu, Mar 31, 2016 at 08:43:29AM -0400, Sean Dague wrote:
> > >> Some more details on progress, because this is getting closer every
> day.
> > >>
> > >> There is now an api-ref target on the Nova project. The entire work in
> > >> progress stream has been rebased into 2 patches to a top level
> api-ref/
> > >> directory structure in the Nova tree -
> > >>
> https://review.openstack.org/#/q/status:open+project:openstack/nova+branch:master+topic:wip_api_docs2
> > >>
> > >> That is a 2 patch series. The first is the infrastructure, the second
> is
> > >> the content for 2 resources (versions and servers). The rendered
> output
> > >> for this is at -
> > >>
> http://docs-draft.openstack.org/63/298763/4/check/gate-nova-api-ref/6983838//api-ref/build/html/
> > >> (you can also pull and build locally with tox -e api-ref)
> > >>
> > >> Karen, Auggy, and Anne continue to work on the wadl data translator
> > >> using the wadl2rst project and fairy-slipper to get various pieces of
> > >> the structured data over. Hopefully we'll see some of those translated
> > >> stacks rendering soon in patch sets.
> > >
> > > I assume at some point we'll be pulling the sphinx extension out to a
> > > separate project so that other projects can use this too? :)
> > >
> > > // jim
> >
> > Yes. I feel like it's probably a milestone 2 activity. Fixing styling
> > and error handling is a lot faster in tree while we sort out all the
> > issues. Once it's good we can move things into something that's pip
> > installable.
>
> Sounds good, thanks for pushing on this. Looking forward to using it in
> ironic. :)


Hi Jim,
A tidbit just for ironic, please review
https://review.openstack.org/#/c/245459 and then we can use that content to
migrate over with the tooling we're creating now. With a good technical
review now your content will be in good shape.
Thanks,
Anne


>
> // jim
>
> >
> >   -Sean
> >
> > --
> > Sean Dague
> > http://dague.net
> >
> >
> __
> > OpenStack Development Mailing List (not for usage questions)
> > Unsubscribe:
> openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [docs] [api] Oh Swagger, where art thou?

[Anne Gentle]

Hi all,

This release I’ve been communicating about moving from WADL to Swagger for
the API reference information on developer.openstack.org. What we've
discovered on the journey is that Swagger doesn't match well for our
current API designs (details below), and while we're not completely giving
up on Swagger, we're also recognizing the engineering effort to maintain
and sustain those efforts isn't going to magically appear.

Sean Dague has put together a proof-of-concept with Compute servers
reference documentation to use Sphinx, RST, parameters files, and some
Sphinx extensions to do a near-copy representation of the API reference
page. We've met with the Nova API team, the API working group, and other
interested developers to make sure our ideas are sound, and so far we have
consensus on forging a new path forward. The review patch is here:
https://review.openstack.org/#/c/292420.

I believe we can still find uses for the Swagger migration for some
projects that match the specification really well. We'll keep outputting
the draft Swagger files to http://developer.openstack.org/draft/swagger/
and continue to look for the use case for Swagger. Perhaps it's a
try-it-out connection to TryStack. Maybe some projects will want to build
clients from those files. We know it's useful, but need to focus efforts
for now.

We know that some OpenStack APIs cannot fit Swagger’s model. For example,
Compute, File Storage, Bare Metal, and Block Storage (nova, manila, ironic,
and cinder projects) have microversions enabled for updates to the request
body as we continue to evolve the API definition, and Swagger has no
mechanism to display the changes between microversions for end-users. As
another example, Compute, Block Storage, File Storage, Databases, and
Networks APIs (nova, cinder, manila, trove, and neutron projects) have an
/actions resource that allows multiple differing request bodies.

I'm writing this email to let you all know there's a new plan coming. We
are using pieces of work from the past efforts to get the best outcome for
sustainable, useful API documentation. The API Reference and WADL files
will remain in the api-site repo until we have a new publishing job that we
can use to flip the switch.

We'll be writing a new specification as well as presenting at an upstream
contributor's talk about Swagger as a standard:
https://www.openstack.org/summit/austin-2016/summit-schedule/events/7723
Once we get the publishing pipeline established, look for review proposals
to your project repos to store API docs there rather than in api-site.

We're going to reboot the migration and get off of WADL. Three cheers for
that. If you’d like to work on these efforts, please stay tuned to the
usual mailing list channels and if you are a docs or API working group
liaison, please stay up-to-date with the plans. Review the upcoming
specification, look for API docs patches in your repo, review those, and
keep the efforts moving.

I'll also attend this week's cross-project meeting to be available for any
questions during open discussion.

Thanks,
Anne, who is going to find her copy of the Oh Brother, Where Art Thou
soundtrack now

--
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs] [api] Why WADL when you can Swagger

[Anne Gentle]

On Thu, Mar 10, 2016 at 8:03 AM, Sean Dague <s...@dague.net> wrote:

> Ok, I'm responding very late to this thread because other bits of the
> release cycle had attention.
>
> A couple of questions.
>
> 1) why are we using the JSON version of the specification instead of the
> YAML one -
>
> https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#format
>
> One of the reasons this is a bit of a hot button issue for me is beyond
> YAML being a bit more readable, it allows *comments* in the file. The
> lack of comments support in JSON makes it really problematic to do
> anything except completely obvious things that will only ever be
> consumed by a computer. Some of these APIs are big, and being able to
> provide annotations to API spec developers is really important.
>

Good question. It's because the migration makes JSON for now, but when I
edit migrated files in http://editor.swagger.io/#/, I import the JSON into
a web-based editor that lets me edit YAML.

The JSON is what's displayed with fairy-slipper but certainly for editing
purposes YAML is preferred. However it's an interesting point about
comments and interchangeability. I'd like a research spike on that.


>
> 2) What is the tox target I can use to build the HTML out of swagger for
> a single project? So that we can iterate here.
>

I added you as a reviewer to https://review.openstack.org/#/c/286659/ as
our interim "just give me HTML" replacement while continuing to work on
this spec with the infra team to figure out how to serve HTML built from
fairy-slipper RST and Swagger files.
https://review.openstack.org/#/c/276484/


>
> 3) What is the current best thinking about microversion specification.
>
> This is the #1 current issue with our API reference site, as we've now
> got 3 (and soon 4) APIs doing this, but 0 support on the API site to
> display this information. If we don't have a near term path forward I
> think we're going to just have to dump all the tools and just go to
> editing the HTML directly.
>
>
I think we'll need a Swagger file per microversion and then work in the
fairy-slipper UI to make each display. Russell Sim the original
fairy-slipper dev, wanted to work on this but he doesn't have time for this
project any more. Considering how far he brought it, I'm super grateful,
but also we need to apply some more devs to solve the display. Karen
Bradshaw has been working on fairy-slipper and we would all welcome more
developers. Can put that fit-n-finish on until we get infra builds sorted.

Let me know if you have more questions after poking around more, thanks for
asking.

Thanks,
Anne


>
>
> On 02/12/2016 04:45 PM, Anne Gentle wrote:
> > Hi all,
> > I wanted to give an update on the efforts to provide improved
> > application developer information on developer.openstack.org
> > <http://developer.openstack.org>. Wrangling this much valuable
> > information and gathering it in a way that helps people is no simple
> > matter. So. We move forward one step at a time.
> >
> > What's new?
> > 
> > This week, with every build of the api-site, we are now running
> > fairy-slipper to migrate from WADL to Swagger for API reference
> > information. Those migrated Swagger files are then copied to
> > developer.openstack.org/draft/swagger
> > <http://developer.openstack.org/draft/swagger>.
> >
> > We know that not all files migrate smoothly. We'd love to get teams
> > looking at these migrated files. Thank you to those of you already
> > submitting fixes!
> >
> > In addition, the infra team is reviewing a spec now so that we can serve
> > API reference information from the developer.openstack.org
> > <http://developer.openstack.org> site:
> > https://review.openstack.org/#/c/276484/
> >
> > Why are we doing all this?
> > --
> > The overall vision is still intact in the original specifications
> > [1][2], however we need to do a lot of web design and front end work to
> > get where we want to be.
> >
> > What can I do?
> > 
> > Check out these Swagger files.
> >
> http://developer.openstack.org/draft/swagger/blockstorage-v1-swagger.json
> >
> http://developer.openstack.org/draft/swagger/blockstorage-v2-swagger.json
> > http://developer.openstack.org/draft/swagger/clustering-v1-swagger.json
> > http://developer.openstack.org/draft/swagger/compute-v2.1-swagger.json
> >
> http://developer.openstack.org/draft/swagger/data-processing-v1.1-swagger.json
> > http://developer.openstack.org/draft/swagger/database-v1-swagger.json
> >
> http://developer.openstack.org/draft/swagger/ident

Re: [openstack-dev] {openstack-dev][tc] Leadership training proposal/info

[Anne Gentle]

On Tue, Mar 1, 2016 at 4:41 PM, Colette Alexander <
colettealexan...@gmail.com> wrote:

> Hello Stackers,
>
> This is the continuation of an ongoing conversation within the TC about
> encouraging the growth of leadership skills within the community that began
> just after the Mitaka summit last year[1]. After being asked by lifeless to
> do a bit of research and discussing needs/wants re: leadership directly
> with TC members, I made some suggestions on an etherpad[2], and was then
> asked to go find out about funding possibilities.
>
> tl;dr - If you're a member of the TC or the Board and would like to attend
> Leadership Training at ZingTrain in Ann Arbor, please get back to me ASAP
> with your contact info and preferred timing/dates for this two-day training
> - also, please let me know whether April 20/21 (or April 21/22) would
> specifically work for you or not.
>


I'd like to, but curious about the possibility of deferring until after the
new TC is elected? I know the seats tend to stay static, but with possibly
half the TC changing it would offer a nice opportunity to get to know any
new members.

Thanks for working on this effort!
Anne


>
>
> Longer version:
> Mark Collier and the Foundation have graciously offered to cover the costs
> of training for a two-day session at ZingTrain in Ann Arbor  - this
> includes the cost of breakfast/lunch for two days as well as two full
> working-days of seminars. Attendees would be responsible for their own
> travel, lodging, and incidental expenses beyond that (hopefully picked up
> by your employer who sees this as an amazing opportunity for your career
> growth). Currently, I've heard the week before the Austin Summit suggested
> by more than one person coming in from out of the country as preferred
> dates, but we've not committed to anything yet, so here might be a great
> time and place to hash that out among interested parties. ZingTrain has
> suggested a cap of ~20 people on the course, but that's not totally firm,
> so it's possible to add more if more are interested, or we could hold two
> separate two-day sessions to accommodate overflow. My ideal mix of people
> include those who are really excited by the idea of training, and those who
> are are seriously skeptical of any leadership training at all. In fact, if
> you've been to leadership training before and have found it to be terrible
> and awful, I think your input would be most valuable on this one. My
> summary of reasoning behind the 'why' of ZingTrain can be found on the
> etherpad I already mentioned[2]. Also, did I mention, the food will be
> amazing? It will be[3].
>
> Some complications: the week before the Newton Summit there will be a set
> of incoming TC members (elected in early April) and likely some TC members
> who will be outgoing. Some possible solutions: we can certainly push back
> training til post-Summit when we can have a set of the 'new' TC, or we can
> sign up anyone interested currently, and allow a limited number of newly
> elected folks who are interested sign on as the election is finished. I
> certainly welcome any thoughts on that.
>
> A note about starting out with the TC/Board for training: this initiative
> began as a set of conversations about leadership as a whole in the entire
> OpenStack community, so the intent with limiting to TC/Board here is not
> exclusion, merely finding the right place to start. My proposal with the TC
> begins with them, because the leadership conversation within OpenStack
> began with them, and the goals of training are really to help them talk
> about defining the issue/problem collectively, within a space designed to
> help people do that.
>
> If you have any questions at all, please feel free to ping me on IRC
> (gothicmindfood) or ask them here.
>
> Thanks everyone!
>
> -colette
>
>
> [1]
> http://eavesdrop.openstack.org/meetings/tc/2015/tc.2015-11-03-20.07.log.html
> [2] https://etherpad.openstack.org/p/Leadershiptraining
> [3] http://www.zingermansdeli.com/
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [docs] Can we get the "configuration reference" of master more often?

[Anne Gentle]

On Thu, Mar 3, 2016 at 8:37 AM, Markus Zoeller <mzoel...@de.ibm.com> wrote:

> The "configuration reference" manual at [1] is really helpful to get
> an overview of the options and we (Nova folks) were wondering if we
> could have that updated more often [2].
>
> Right now it is from November 2015 [3] and we (Nova folks) put a lot of
> effort this cycle in improving the help of our config options but they
> aren't yet (fully) reflected in that guide.
>
> Different options would be:
> A: per milestone
> B: per merge of a commit which contains "DocImpact" in its message
> C: daily/nightly
>
> Personally I think daily/nightly would be sufficient.
>
> AFAIK the generation of that guide is done with [4] and IIUC there is
> no necessity of human intervention in that process, or did I miss
> something?
>

Yes. The necessity of a human running that tool and creating a patch.

Would love help automating, of course!

Thanks,
Anne


>
> References:
> [1]
>
> http://docs.openstack.org/draft/config-reference/compute/config-options.html
> [2]
>
> http://eavesdrop.openstack.org/irclogs/%23openstack-nova/%23openstack-nova.2016-03-03.log.html#t2016-03-03T13:40:15
> [3]
>
> http://eavesdrop.openstack.org/irclogs/%23openstack-doc/%23openstack-doc.2016-03-03.log.html#t2016-03-03T13:51:15
> [4]
>
> https://github.com/openstack/openstack-doc-tools/tree/master/autogenerate_config_docs
>
> Regards, Markus Zoeller (markus_z)
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Openstack-operators] OpenStack Contributor Awards

[Anne Gentle]

Or they use it to do a cool demo of running apps on an OpenStack cloud.

On Tue, Mar 1, 2016 at 2:04 PM, Tim Bell <tim.b...@cern.ch> wrote:

>
> Just to check, does OpenStack run on a Raspberry Pi ? Could cause some
> negative comments if it was
> not compatible/sized for a basic configuration.
>
> Tim
>
>
>
>
>
> On 01/03/16 20:41, "Thomas Goirand" <z...@debian.org> wrote:
>
> >On 03/01/2016 11:30 PM, Tom Fifield wrote:
> >> Excellent, excellent.
> >>
> >> What's the best place to buy Raspberry Pis these days?
> >
> >One of the 2 official sites:
> >https://www.element14.com/community/community/raspberry-pi
> >
> >The Pi 3 is the super nice shiny new stuff, with 64 arm bits.
> >
> >Cheers,
> >
> >Thomas Goirand (zigo)
> >
> >
> >Hopefully, with it, there will be no need of raspbian anymore (it was
> >there because of a very poor choice of CPU in model 1 and 2, just below
> >what the armhf builds required, forcing to use armel which is arm v4
> >instruction sets).
> >
> >
> >
> >__
> >OpenStack Development Mailing List (not for usage questions)
> >Unsubscribe:
> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> >http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
> ___
> OpenStack-operators mailing list
> openstack-operat...@lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-operators
>
>


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Google Sumer of Code 2016 - Call for ideas and mentors (deadline 19/02/2016)

[Anne Gentle]

Thanks for putting in the effort, Victoria! We learn each year we apply.

Anne

On Mon, Feb 29, 2016 at 2:02 PM, Victoria Martínez de la Cruz <
victo...@vmartinezdelacruz.com> wrote:

> Updates on this topic. Unfortunately we didn't make it for this year.
> We'll apply next year again, thanks all for your support.
>
> Best,
>
> Victoria
>
> 2016-02-15 16:55 GMT-03:00 Victoria Martínez de la Cruz <
> victo...@vmartinezdelacruz.com>:
>
>> Friendly reminder, we are still looking for mentors and internship ideas.
>> Join us [0] and submit your internship project ideas in [1].
>>
>> The deadline for our application as mentoring organization is 19/02/2016
>>
>> [0] https://wiki.openstack.org/wiki/GSoC2016
>> [1] https://wiki.openstack.org/wiki/Internship_ideas
>>
>> 2016-02-01 16:12 GMT-03:00 Victoria Martínez de la Cruz <
>> victo...@vmartinezdelacruz.com>:
>>
>>> Hi all,
>>>
>>> Google Summer of Code (GSoC) is a program that matches mentoring
>>> organizations with college and university student developers who are paid
>>> to write open source code. It has been around 2005 and we had been accepted
>>> as a mentor organization in only one opportunity (2014) having a great
>>> outcome for both interns and for our community. We expect to be able to
>>> join this year again, but for that, we will need your help.
>>>
>>> Mentors
>>>
>>> We need to submit our application as a mentoring organization, but for
>>> that, we need to have a clear outline of what different projects we have
>>> for interns to work on.
>>>
>>> *** The deadline for mentoring organizations applications is
>>> 19/02/2016. ***
>>>
>>> If you are interested in mentoring but you have doubts about it, please
>>> feel free to reach us here or on #openstack-gsoc. We will be happy to reply
>>> any doubt you may have about mentoring for this internship. Also, you can
>>> check out this guide [0].
>>>
>>> If you are already convinced that you want to join us as a mentor for
>>> this round, add your name in the OpenStack Google Summer of Code 2016 wiki
>>> page [1] and add your project ideas in [2]. Make sure you leave your
>>> contact information in the OpenStack GSoC 2016 wiki and that you add all
>>> the important details about the project idea. Also reach us if there is
>>> something you are not certain about.
>>>
>>> Interns
>>>
>>> Whereas we don't know yet if we are going to make it as a mentoring
>>> organization for this round, if you want to join us as an intern and you
>>> want to help OpenStack to get selected as a mentoring organization, you can
>>> help us proposing different tasks for the various projects we have in our
>>> ecosystem.
>>>
>>> For your inspiration, you can check out past projects in [3] and [4].
>>>
>>> Looking forward to see GSoC happening again in our community!
>>>
>>> Thanks,
>>>
>>> Victoria
>>>
>>> [0] http://en.flossmanuals.net/gsocmentoring/
>>> [1] https://wiki.openstack.org/wiki/GSoC2016
>>> [2] https://wiki.openstack.org/wiki/Internship_ideas
>>> [3] https://wiki.openstack.org/wiki/GSoC2014
>>> [4] https://wiki.openstack.org/wiki/GSoC2015
>>>
>>
>>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [openstack-infra] Getting Started Guide

[Anne Gentle]

On Mon, Feb 22, 2016 at 9:45 PM, Kenny Johnston <kencjohns...@gmail.com>
wrote:

>
>- The Product Work Group (PWG) uses the openstack-user-stories
>repository and gerrit to review and produce .rst formatted user stories
>- The PWG is comprised (mostly) of non-developers
>- We've found the Getting Started guide a bit inadequate for pointing
>new PWG contributors to in order to get them up and running with our
>process, and investigated creating a separate guide of our own to cover
>getting setup with Windows machines and common issues with corporate
>firewalls
>- I heard at the Ops Summit that the getting started guide should be
>THE place we point new contributors to learn how to get setup for
>contributing
>
> Would it be palatable to submit patches updating the current guide to
> cover non-developer getting started instructions?
>

Hi Kenny -

In docs we started our own contributor guide and then point to the infra
guide as needed.

http://docs.openstack.org/contributor-guide/index.html

What do you think about something like that? Lets you have your own review
team and lets the infra guide remain the infra guide.

Anne


>
> Thanks!
>
> --
> Kenny Johnston
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] A proposal to separate the design summit

[Anne Gentle]

ntributors who would like to
> participate in this sessions can collect and relay feedback to other team
> members for implementation (similar to the Ops midcycle). Other
> contributors will also want to get more involved in the conference, whether
> that's giving presentations or hearing user stories.
>
> The split should ideally reduce the needs to organize separate in-person
> mid-cycle events. If some are still needed, the main conference venue and
> time could easily be used to provide space for such midcycle events (given
> that it would end up happening in the middle of the cycle).
>

I like the reduction in separate midcycles.


>
> In practice, the split means that we need to stagger the events and
> cycles. We have a long time between Barcelona and the Q1 Summit in the US,
> so the idea would be to use that long period to insert a smaller cycle
> (Ocata) with a release early March, 2017 and have the first specific
> contributors event at the start of the P cycle, mid-February, 2017. See the
> attached PDF for a visual explanation. With the already-planned events in
> 2016 and 2017 it is the earliest we can make the transition. We'd have a
> last, scaled-down design summit in Barcelona to plan the shorter cycle.
>

Does this still mean there are OpenStack conferences every six months?


>
> With that setup, we hope that we can restore the productivity and focus of
> the face-to-face contributors gathering, reduce the need to have midcycle
> events for social bonding and team building, keep the cost of getting all
> contributors together once per cycle under control, maintain the feedback
> loops with all the constituents of the OpenStack community at the main
> event, and better align the timing of each event with the reality of the
> release cycles.
>

Could you describe the discussion points around timing besides being
related to releases?

Is there any case for annual large events and smaller release-oriented
events?


>
> NB: You will note that I did not name the separated event "Design Summit"
> -- that is because Design will now be split into feedback/requirements
> gathering (the "why" at the main event) and execution planning and
> kickstarting (the "how" at the contributors-oriented event), so that name
> doesn't feel right anymore. We can bikeshed on the name for the new event
> later :)
>

Oh dear, let's not. :)

Thanks Thierry -
Anne


>
> Comments, thoughts ?
>
> --
> Thierry Carrez (ttx)
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [horizon] [octavia] [heat] [docs] Meeting times and the -cp meeting room

[Anne Gentle]

On Mon, Feb 22, 2016 at 8:49 AM, Anne Gentle <annegen...@justwriteclick.com>
wrote:

> Hi all,
>
> The docs team has been seeking a new meeting time for North America/Europe
> for a couple of months now. With that search comes the search for a meeting
> room. Here's what we know:
>
> We want Wed 20:00.
>
> Heat, Horizon, and Octavia are currently in the three meeting rooms in the
> time slot we want.
>
> We've requested the use of #openstack-meeting-cp but there's some who
> express a need for ad-hoc meeting times in that room.
>
> The meetbot is enabled in #openstack-doc.
>
> So, could we either use #openstack-meeting-cp or #openstack-doc? Or have
> Heat, Horizon, or Octavia been looking for another time slot by chance?
>
> Thanks for ideas.
>

New idea: 1900 Wed. has free meeting rooms. I've updated the review, please
vote on this time:

https://review.openstack.org/271361

Thanks Andreas for looking!

Anne


>
> Anne
>
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [horizon] [octavia] [heat] [docs] Meeting times and the -cp meeting room

[Anne Gentle]

Hi all,

The docs team has been seeking a new meeting time for North America/Europe
for a couple of months now. With that search comes the search for a meeting
room. Here's what we know:

We want Wed 20:00.

Heat, Horizon, and Octavia are currently in the three meeting rooms in the
time slot we want.

We've requested the use of #openstack-meeting-cp but there's some who
express a need for ad-hoc meeting times in that room.

The meetbot is enabled in #openstack-doc.

So, could we either use #openstack-meeting-cp or #openstack-doc? Or have
Heat, Horizon, or Octavia been looking for another time slot by chance?

Thanks for ideas.

Anne

-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] [tc] "No Open Core" in 2016

[Anne Gentle]

On Wed, Feb 17, 2016 at 12:20 PM, Jay Pipes <jaypi...@gmail.com> wrote:

> On 02/17/2016 09:30 AM, Doug Hellmann wrote:
>
>> Excerpts from Mike Perez's message of 2016-02-17 03:21:51 -0800:
>>
>>> On 02/16/2016 11:30 AM, Doug Hellmann wrote:
>>>
>>>> So I think the project team is doing everything we've asked.  We
>>>> changed our policies around new projects to emphasize the social
>>>> aspects of projects, and community interactions. Telling a bunch
>>>> of folks that they "are not OpenStack" even though they follow those
>>>> policies is rather distressing.  I think we should be looking for
>>>> ways to say "yes" to new projects, rather than "no."
>>>>
>>>
>>> My disagreements with accepting Poppy has been around testing, so let me
>>> reiterate what I've already said in this thread.
>>>
>>> The governance currently states that under Open Development "The project
>>> has core reviewers and adopts a test-driven gate in the OpenStack
>>> infrastructure for changes" [1].
>>>
>>> If we don't have a solution like OpenCDN, Poppy has to adopt a reference
>>> implementation that is a commercial entity, and infra has to also be
>>> dependent on it. I get Infra is already dependent on public cloud
>>> donations, but if we start opening the door to allow projects to bring
>>> in those commercial dependencies, that's not good.
>>>
>>
>> Only Poppy's test suite would rely on that, though, right? And other
>> projects can choose whether to co-gate with Poppy or not. So I don't see
>> how this limitation has an effect on anyone other than the Poppy team.
>>
>
> But what would really be tested in Poppy without any commercial CDN
> vendor? Nothing functional, right? I believe the fact that Poppy cannot be
> functionally tested in the OpenStack CI gate basically disqualifies it from
> being "in OpenStack".
>

I do want end-users to have CDN, I do. And I'm a pragmatist as well so the
"open core" arguments aren't as important to me.

That said, for me, since poppy itself doesn't offer/run/maintain the
service but instead simply offers an API on top of CDN provider's APIs, I
don't think it's necessary to govern it in OpenStack.

Thanks,
Anne


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



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Nova][API] Does nova API allow the server_id parem as DB index?

[Anne Gentle]

On Wed, Feb 17, 2016 at 8:49 AM, Sean Dague <s...@dague.net> wrote:

> I did push a speculative patch which would address this by not exposing
> the lookup by int id backdoor - https://review.openstack.org/#/c/281277/
> - the results were better than I expected.
>
> Andrey, is this going to negatively impact the openstack/ec2 project at
> all if we do it?
>

Bug tracking here: https://bugs.launchpad.net/nova/+bug/1545922


>
> -Sean
>
>
> On 02/16/2016 06:49 AM, Sean Dague wrote:
> > This was needed originally for ec2 support (which requires an integer
> > id). It's not really the db index per say, just another id value which
> > is valid (though hidden) for the server.
> >
> > Before unwinding this issue we *must* make sure that the openstack/ec2
> > project does not need access to it.
> >
> > On 02/15/2016 09:36 PM, Alex Xu wrote:
> >> I don't think our API supports get servers by DB index is good idea. So
> >> I prefer we remove it in the future with microversions. But for now,
> >> yes, it is here.
> >>
> >> 2016-02-16 8:03 GMT+08:00 少合冯 <lvmxhs...@gmail.com
> >> <mailto:lvmxhs...@gmail.com>>:
> >>
> >> I guess others may ask the same questions.
> >>
> >> I read the nova API doc:
> >> such as this API:
> >> http://developer.openstack.org/api-ref-compute-v2.1.html#showServer
> >>
> >> GET /v2.1/​{tenant_id}​/servers/​{server_id}​
> >> *Show server details*
> >>
> >>
> >> *Request parameters*
> >> ParameterStyle   TypeDescription
> >> tenant_idURI csapi:UUID
> >>
> >> The UUID of the tenant in a multi-tenancy cloud.
> >>
> >> server_idURI csapi:UUID
> >>
> >> The UUID of the server.
> >>
> >>
> >> But I can get the server by DB index:
> >>
> >> curl -s -H X-Auth-Token:6b8968eb38df47c6a09ac9aee81ea0c6
> >>
> http://192.168.2.103:8774/v2.1/f5a8829cc14c4825a2728b273aa91aa1/servers/2
> >> {
> >> "server": {
> >> "OS-DCF:diskConfig": "MANUAL",
> >> "OS-EXT-AZ:availability_zone": "nova",
> >> "OS-EXT-SRV-ATTR:host": "shaohe1",
> >> "OS-EXT-SRV-ATTR:hypervisor_hostname": "shaohe1",
> >> "OS-EXT-SRV-ATTR:instance_name": "instance-0002",
> >> "OS-EXT-STS:power_state": 1,
> >> "OS-EXT-STS:task_state": "migrating",
> >> "OS-EXT-STS:vm_state": "error",
> >> "OS-SRV-USG:launched_at": "2015-12-18T07:41:00.00",
> >> "OS-SRV-USG:terminated_at": null,
> >> ..
> >> }
> >> }
> >>
> >> and the code really allow it use  DB index
> >>
> https://github.com/openstack/nova/blob/master/nova/compute/api.py#L1939
> >>
> >>
>  __
> >> OpenStack Development Mailing List (not for usage questions)
> >> Unsubscribe:
> >> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> >> <
> http://openstack-dev-requ...@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-requ...@lists.openstack.org?subject:unsubscribe
> >> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
> >>
> >
> >
>
>
> --
> Sean Dague
> http://dague.net
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Nova][API] Does nova API allow the server_id parem as DB index?

[Anne Gentle]

On Mon, Feb 15, 2016 at 6:03 PM, 少合冯 <lvmxhs...@gmail.com> wrote:

> I guess others may ask the same questions.
>
> I read the nova API doc:
> such as this API:
> http://developer.openstack.org/api-ref-compute-v2.1.html#showServer
>
> GET /v2.1/​{tenant_id}​/servers/​{server_id}​
> *Show server details*
>
>
> *Request parameters*
> ParameterStyleTypeDescription
> tenant_id URI csapi:UUID
>
> The UUID of the tenant in a multi-tenancy cloud.
> server_id URI csapi:UUID
>
> The UUID of the server.
>
> But I can get the server by DB index:
>
> curl -s -H X-Auth-Token:6b8968eb38df47c6a09ac9aee81ea0c6
> http://192.168.2.103:8774/v2.1/f5a8829cc14c4825a2728b273aa91aa1/servers/2
> {
> "server": {
> "OS-DCF:diskConfig": "MANUAL",
> "OS-EXT-AZ:availability_zone": "nova",
> "OS-EXT-SRV-ATTR:host": "shaohe1",
> "OS-EXT-SRV-ATTR:hypervisor_hostname": "shaohe1",
> "OS-EXT-SRV-ATTR:instance_name": "instance-0002",
> "OS-EXT-STS:power_state": 1,
> "OS-EXT-STS:task_state": "migrating",
> "OS-EXT-STS:vm_state": "error",
> "OS-SRV-USG:launched_at": "2015-12-18T07:41:00.00",
> "OS-SRV-USG:terminated_at": null,
> ..
> }
> }
>
> and the code really allow it use  DB index
> https://github.com/openstack/nova/blob/master/nova/compute/api.py#L1939
>
>
Nice find. Can you log this as an API bug and we'll triage it -- can even
help you fix it on the site if you like.

https://bugs.launchpad.net/openstack-api-site/+filebug

Basically, click that link, write a short summary, then copy and paste in
this email's contents, it has lots of good info.

Let me know if you'd also like to fix the bug on the site.

And hey nova team, if you think it's actually an API bug, we'll move it
over to you.

Thanks for reporting it!
Anne



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


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [docs] [api] Why WADL when you can Swagger

[Anne Gentle]

Hi all,
I wanted to give an update on the efforts to provide improved application
developer information on developer.openstack.org. Wrangling this much
valuable information and gathering it in a way that helps people is no
simple matter. So. We move forward one step at a time.

What's new?

This week, with every build of the api-site, we are now running
fairy-slipper to migrate from WADL to Swagger for API reference
information. Those migrated Swagger files are then copied to
developer.openstack.org/draft/swagger.

We know that not all files migrate smoothly. We'd love to get teams looking
at these migrated files. Thank you to those of you already submitting
fixes!

In addition, the infra team is reviewing a spec now so that we can serve
API reference information from the developer.openstack.org site:
https://review.openstack.org/#/c/276484/

Why are we doing all this?
--
The overall vision is still intact in the original specifications [1][2],
however we need to do a lot of web design and front end work to get where
we want to be.

What can I do?

Check out these Swagger files.
http://developer.openstack.org/draft/swagger/blockstorage-v1-swagger.json
http://developer.openstack.org/draft/swagger/blockstorage-v2-swagger.json
http://developer.openstack.org/draft/swagger/clustering-v1-swagger.json
http://developer.openstack.org/draft/swagger/compute-v2.1-swagger.json
http://developer.openstack.org/draft/swagger/data-processing-v1.1-swagger.json
http://developer.openstack.org/draft/swagger/database-v1-swagger.json
http://developer.openstack.org/draft/swagger/identity-admin-v2-swagger.json
http://developer.openstack.org/draft/swagger/identity-extensions-v2-swagger.json
http://developer.openstack.org/draft/swagger/identity-extensions-v3-swagger.json
http://developer.openstack.org/draft/swagger/identity-v2-swagger.json
http://developer.openstack.org/draft/swagger/identity-v3-swagger.json
http://developer.openstack.org/draft/swagger/image-v1-swagger.json
http://developer.openstack.org/draft/swagger/networking-extensions-v2-swagger.json
http://developer.openstack.org/draft/swagger/networking-v2-swagger.json
http://developer.openstack.org/draft/swagger/objectstorage-v1-swagger.json
http://developer.openstack.org/draft/swagger/orchestration-v1-swagger.json
http://developer.openstack.org/draft/swagger/share-v1-swagger.json
http://developer.openstack.org/draft/swagger/telemetry-v2-swagger.json

If you see a problem in the original WADL, log it here:
https://bugs.launchpad.net/openstack-api-site. If you see a problem with
the migration tool, log it here:
https://bugs.launchpad.net/openstack-doc-tools.

When will the work be completed?


I had hoped to have more to show by this point, but I await the infra
team's review of the server spec above, and we continue to work on the bugs
in the migration and output. Once the server spec work is complete, we can
release the draft site.

What if I have more questions?
--
You can always hop onto #openstack-doc or #openstack-sdks to ask me or
another API working group member for guidance.

Last but not least, if you want to learn more about Swagger in the upstream
contributors track at the Summit, vote for this session:
https://www.openstack.org/summit/austin-2016/vote-for-speakers/presentation/7723

Thanks,
Anne

--
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com

1.
http://specs.openstack.org/openstack/docs-specs/specs/mitaka/app-guides-mitaka-vision.html
2.
http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Docs] Changes for OpenStack API guides

[Anne Gentle]

Hi --
Here's some specs for you to peruse to get a lot of background, and the
blog post and -dev mailing list post that went out. You can also ask me
directly, annegentle on IRC or through email. It's a lot and only two-three
people are working on this effort centrally with the rest of the work
across all projects.

http://lists.openstack.org/pipermail/openstack-dev/2016-January/083670.html
http://www.openstack.org/blog/2016/01/whats-next-for-application-developer-guides/

http://specs.openstack.org/openstack/docs-specs/specs/mitaka/app-guides-mitaka-vision.html
http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html

The latest progress is in these reviews:
Run a virtual server to serve REST API: https://review.openstack.org/276484
Build scripts to copy Swagger to developer.openstack.org:
https://review.openstack.org/#/c/269809/
Migration script to make Swagger from current WADL:
https://review.openstack.org/#/c/270819/

In January I sent emails directly to all the API liaisons from
http://specs.openstack.org/openstack/api-wg/liaisons.html so sounds like
the word is getting out! Thanks for asking.

Anne


On Fri, Feb 5, 2016 at 9:50 AM, Smigiel, Dariusz <dariusz.smig...@intel.com>
wrote:

> Hello Anne,
>
> I’m working on “moving to Keystone v3 API” spec for Neutron [1].
>
> HenryG mentioned, that in next release or so, there will be change how to
> describe changes connected to API [2].
>
> In spec I’m mentioning, that some changes are required to Networking API
> v2 [3], so would like to know, how it supposed to be handled.
>
>
>
> If you could point me to some place where I can find extra info about
> changes, It would be very helpful.
>
>
>
> Thanks,
>
> Dariusz (dasm) Smigiel
>
>
>
> [1] https://review.openstack.org/#/c/257362/
>
> [2]
> http://lists.openstack.org/pipermail/openstack-dev/2016-January/083670.html
>
> [3] http://developer.openstack.org/api-ref-networking-v2.html
>
>
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [Docs] Changes for OpenStack API guides

[Anne Gentle]

On Fri, Feb 5, 2016 at 9:50 AM, Smigiel, Dariusz <dariusz.smig...@intel.com>
wrote:

> Hello Anne,
>
> I’m working on “moving to Keystone v3 API” spec for Neutron [1].
>
> HenryG mentioned, that in next release or so, there will be change how to
> describe changes connected to API [2].
>
> In spec I’m mentioning, that some changes are required to Networking API
> v2 [3], so would like to know, how it supposed to be handled.
>
>
>
> If you could point me to some place where I can find extra info about
> changes, It would be very helpful.
>

Also, for small feature changes happening now, it's fine to simply update
the WADL file as the migrations will be ongoing. You can find neutron API
reference information here:
https://github.com/openstack/api-site/tree/master/api-ref/src/wadls/networking-api/src/wadl

which is published to
http://developer.openstack.org/api-ref-networking-v2.html and will continue
to be while we work on changes away from WADL.
Thanks,
Anne


>
>
> Thanks,
>
> Dariusz (dasm) Smigiel
>
>
>
> [1] https://review.openstack.org/#/c/257362/
>
> [2]
> http://lists.openstack.org/pipermail/openstack-dev/2016-January/083670.html
>
> [3] http://developer.openstack.org/api-ref-networking-v2.html
>
>
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] the trouble with names

[Anne Gentle]

On Thu, Feb 4, 2016 at 7:33 AM, Sean Dague <s...@dague.net> wrote:

> On 02/04/2016 08:18 AM, Doug Hellmann wrote:
> > Excerpts from Hayes, Graham's message of 2016-02-04 12:54:56 +:
> >> On 04/02/2016 11:40, Sean Dague wrote:
> >>> A few issues have crept up recently with the service catalog, API
> >>> headers, API end points, and even similarly named resources in
> >>> different resources (e.g. backup), that are all circling around a key
> >>> problem. Distributed teams and naming collision.
> >>>
> >>> Every OpenStack project has a unique name by virtue of having a git
> >>> tree. Once they claim 'openstack/foo', foo is theirs in the
> >>> OpenStack universe for all time (or until trademarks say otherwise).
> >>> Nova in OpenStack will always mean one project.
> >>>
> >>> There has also been a desire to replace project names with
> >>> common/generic names, in the service catalog, API headers, and a few
> >>> other places. Nova owns 'compute'. Except... that's only because we
> >>> all know that it does. We don't *actually* have a registry for those
> >>> values.
> >>>
> >>> So the code names are well regulated, the common names, that we
> >>> encourage use of, are not. Devstack in tree code defines some
> >>> conventions. However with the big tent, things get kind of squirely
> >>> pretty quickly. Congress registering 'policy' as their endpoint type
> >>> is a good example of that -
> >>>
> https://github.com/openstack/congress/blob/master/devstack/plugin.sh#L147
> >>>
> >>>  Naming is hard. And trying to boil down complicated state machines
> >>> to one or two word shiboliths means that inevitably we're going to
> >>> find some words just keep cropping up: policy, flavor, backup, meter.
> >>> We do however need to figure out a way forward.
> >>>
> >>> Lets start with the top level names (resource overlap cascades from
> >>> there).
> >>>
> >>> What options do we have?
> >>>
> >>> 1) Use the names we already have: nova, glance, swift, etc.
> >>>
> >>> Upside, collision problem is solved. Downside, you need a secret
> >>> decoder ring to figure out what project does what.
> >>>
> >>> 2) Have a registry of "common" names.
> >>>
> >>> Upside, we can safely use common names everywhere and not fear
> >>> collision down the road.
> >>>
> >>> Downside, yet another contention point.
> >>>
> >>> A registry would clearly be under TC administration, though all the
> >>> heavy lifting might be handed over to the API working group. I still
> >>> imagine collision around some areas might be contentious.
> >>
> >> ++ to a central registry. It could easily be added to the projects.yaml
> >> file, and is a single source of truth.
> >
> > Although I realized that the projects.yaml file only includes official
> > projects right now, which would mean new projects wouldn't have a place
> > to register terms. Maybe that's a feature?
>
> It seems like it's a feature.
>
> That being said, projects.yaml is pretty full right now. And, it's not
> clear that common name <-> project name is a 1 to 1 mapping.
>
> For instance, Nova is getting very close to exposing a set of scheduler
> resources. For future proofing we would like to do that on a dedicated
> new endpoint from day one so that potential future split out of the code
> would not impact how APIs look in the service catalog or to consumers.
> There would be no need to have proxy apis in Nova for compatibility in
> the future.
>
> So this feels like a separate registry for service common name, which
> maps N -> 1 to a project.
>

Project names should not be exposed to end users.

Maybe the service names belong in an example, vetted service catalog as a
place to look to see if your name is already taken. I sense we have to
first start with endpoints, then move to the resources, and honestly I feel
lately "let the best API design win." For example, with PayPal and Stripe,
there are differentiators that would cause a dev to choose one over
another. PayPal has a /payments resource and Stripe has a /charges
resource. Those resources are where some of the conflict is starting to be
seen for us in OpenStack with backups. If we expect end users to use the
whole cloud then we need to outline the resources that are reserved already
to avoid end-user con

[openstack-dev] App dev guides update [nova] [keystone] [cinder] [swift] [glance] [neutron] [trove] [heat] [manila] [ceilometer] [sahara] [senlin]

[Anne Gentle]

 to Swagger
files and stored in the api-site repository. The WADL files will be
deleted; you can retrieve them from Git.

If your project does not have a WADL file, then you write Swagger plus RST
to document your API calls, parameters, and reference information. You can
generate Swagger from annotations or create Swagger from scratch that you
store in the api-site repository. You should review, store, and build RST
for conceptual or how-to information from within your project team’s
repository.

All projects should use this set of API documentation guidelines from the
OpenStack API working group any time their service has a REST API. This
document tells you what and how much to write. If you follow the suggested
outline, your API guide will be accurate and complete.

After the source files and build jobs exist, the docs are built to
developer.openstack.org.

Where can I get help for my project’s API Guides?

These specifications describe the details: Application Developer Guides and
Rework API Reference Information.

You can ask questions in #openstack-sdks or #openstack-docs on IRC. We
await those magical API docs fairies who grant wishes, but in the meantime
but we can point you in the right direction and give you the tools for your
quest.

What if I still have questions?

Contact me, Anne Gentle, by email or IRC and I’ll get back to you as soon
as possible.

I’m eager to enable our audience with great user-centric docs and hope that
you’ll join us as we fulfill the vision.--
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [doc] [api] Vision and changes for OpenStack API Guides

[Anne Gentle]

On Fri, Jan 8, 2016 at 7:35 PM, Anne Gentle <annegen...@justwriteclick.com>
wrote:

>
>
> On Fri, Jan 8, 2016 at 3:39 PM, Anne Gentle <annegen...@justwriteclick.com
> > wrote:
>
>> Hi all,
>>
>> With milestone 2 coming next week I want to have a chat about API guides,
>> API reference information, and the http://developer.openstack.org site.
>> We have a new tool, fairy-slipper [1], yep you read that right, that can
>> migrate files from WADL to Swagger as well as serve up reference info. We
>> also have new build jobs that can build API guides right from your projects
>> repo to developer.openstack.org.
>>
>> There's a lot going on, so I've got an agenda item for next week to hold
>> a cross-project meeting so that you can send a team representative to get
>> the scoop on API guides and bring it back to your teams. I've fielded great
>> questions from a few teams, and want to ensure everyone's in the loop.
>>
>> A pair of specs set the stage for this work, feel free to review these in
>> advance of the meeting and come with questions. [2] [3]
>>
>> Join me next week at the first pop-up Cross Project meeting, Tuesday at
>> 1700, in #openstack-meeting-cp. Feel free to add to the agenda at
>>
>
>
Double whoops, I mean Tuesday at 2100.
Anne


> Woops, agenda here:
>
>
> https://wiki.openstack.org/wiki/Meetings/CrossProjectMeeting#Proposed_agenda
>
>
>
>>
>> Thanks,
>> Anne
>>
>>
>> 1. https://github.com/openstack/fairy-slipper
>> 2. mitaka spec:
>> http://specs.openstack.org/openstack/docs-specs/specs/mitaka/app-guides-mitaka-vision.html
>> 3. liberty spec:
>> http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html
>>
>> --
>> Anne Gentle
>> Rackspace
>> Principal Engineer
>> www.justwriteclick.com
>>
>
>
>
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [doc] [api] Vision and changes for OpenStack API Guides

[Anne Gentle]

On Fri, Jan 8, 2016 at 3:39 PM, Anne Gentle <annegen...@justwriteclick.com>
wrote:

> Hi all,
>
> With milestone 2 coming next week I want to have a chat about API guides,
> API reference information, and the http://developer.openstack.org site.
> We have a new tool, fairy-slipper [1], yep you read that right, that can
> migrate files from WADL to Swagger as well as serve up reference info. We
> also have new build jobs that can build API guides right from your projects
> repo to developer.openstack.org.
>
> There's a lot going on, so I've got an agenda item for next week to hold a
> cross-project meeting so that you can send a team representative to get the
> scoop on API guides and bring it back to your teams. I've fielded great
> questions from a few teams, and want to ensure everyone's in the loop.
>
> A pair of specs set the stage for this work, feel free to review these in
> advance of the meeting and come with questions. [2] [3]
>
> Join me next week at the first pop-up Cross Project meeting, Tuesday at
> 1700, in #openstack-meeting-cp. Feel free to add to the agenda at
>

Woops, agenda here:

https://wiki.openstack.org/wiki/Meetings/CrossProjectMeeting#Proposed_agenda



>
> Thanks,
> Anne
>
>
> 1. https://github.com/openstack/fairy-slipper
> 2. mitaka spec:
> http://specs.openstack.org/openstack/docs-specs/specs/mitaka/app-guides-mitaka-vision.html
> 3. liberty spec:
> http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html
>
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

[openstack-dev] [doc] [api] Vision and changes for OpenStack API Guides

[Anne Gentle]

Hi all,

With milestone 2 coming next week I want to have a chat about API guides,
API reference information, and the http://developer.openstack.org site. We
have a new tool, fairy-slipper [1], yep you read that right, that can
migrate files from WADL to Swagger as well as serve up reference info. We
also have new build jobs that can build API guides right from your projects
repo to developer.openstack.org.

There's a lot going on, so I've got an agenda item for next week to hold a
cross-project meeting so that you can send a team representative to get the
scoop on API guides and bring it back to your teams. I've fielded great
questions from a few teams, and want to ensure everyone's in the loop.

A pair of specs set the stage for this work, feel free to review these in
advance of the meeting and come with questions. [2] [3]

Join me next week at the first pop-up Cross Project meeting, Tuesday at
1700, in #openstack-meeting-cp. Feel free to add to the agenda at

Thanks,
Anne


1. https://github.com/openstack/fairy-slipper
2. mitaka spec:
http://specs.openstack.org/openstack/docs-specs/specs/mitaka/app-guides-mitaka-vision.html
3. liberty spec:
http://specs.openstack.org/openstack/docs-specs/specs/liberty/api-site.html

-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [doc] DocImpact vs. reno

[Anne Gentle]

On Fri, Dec 18, 2015 at 12:03 PM, Sean Dague <s...@dague.net> wrote:

> Recently noticed that a new job ended up on all nova changes that was
> theoertically processing commit messages for DocImpact. It appears to be
> part of this spec -
>
> http://specs.openstack.org/openstack/docs-specs/specs/mitaka/review-docimpact.html
>
> First, a heads up would be good. Nova burns a lot of nodes (i.e. has a
> lot of patch volume), so this just decreased everyone's CI capacity
> noticably.
>
>
Lana talked to infra first, specifically Josh Hesketh if my memory serves,
and I hadn't heard there would be any CI impact -- what's the root cause?
Not sure I get why this spec is part of a technical node requirement
change, so please explain more, or Josh please explain more. Then we can
dig in further. Lana's out til the new year and this is my last day for the
year too so let's see what we need to do short term and long term.

Seems especially odd when this should be a low patch volume time so help me
understand the tie-in.


> Secondly, this all seems like the wrong direction. We've got reno now,
> which is extremely useful for documenting significant changes in the
> code base that need to be reflected up. We've dropped UpgradeImpact for
> an upgrade comment in reno, which is *so* much better.
>
>
To me, reno is for release notes only, not for doc impact further than
release notes. DocImpact is for any document and for a while the number of
bugs generated in openstack-manuals were too numerous to be meaningfully
triaged.


> It seems like using reno instead of commit message tags would be much
> better for everyone here.
>
>
It's more complex, let's dig in another layer.

Anne


> -Sean
>
> --
> Sean Dague
> http://dague.net
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Volume attachment APIs CRUD inconsistencies

[Anne Gentle]

On Fri, Dec 11, 2015 at 7:33 PM, Matt Riedemann <mrie...@linux.vnet.ibm.com>
wrote:

>
>
> On 12/11/2015 1:48 PM, Sam Matzek wrote:
>
>> The CRUD operations for Nova volume attachments have inconsistencies
>> between documentation and implementation.  Additionally, the read/get
>> operation is implemented twice under different URIs.  What is Nova's
>> direction for volume attachment APIs and how should the following
>> discrepancies be resolved?
>>
>> The current state of affairs is:
>> CREATE (volume attach) is documented twice under two different URIs: [1]
>> and [2], but only os-volume_attachments [1] is implemented [3].
>>
>
Matt, can you look a little deeper into what happened to
os-volume_attachments? I'm worried we've missed one of the extensions.

As for the docs, I thought we put in redirects from v2 to v2.1 but I need
to investigate.

Anne


> Attach volume as an action on the servers URI appears to have been part
>> of the Nova V3 API, but its implementation no longer exists.
>> Is it the future direction to have volume attach and detach done as
>> server actions?
>>
>> READ is implemented twice and documented twice under two different URIs:
>> os-volume_attachments [5] and server details [6]
>> The two implementations do not return the same information and the only
>> bit of information that is common between them is the volume ID.
>> Why do we have two implementations and is one preferred over the other?
>> Should one be deprecated and eventually removed with all enhancements
>> going into the other?
>>
>> UPDATE is implemented [4] but not documented.
>>
>> DELETE (detach) only appears to be implemented and documented once: [7]
>>
>> A blueprint proposal exists [8] to enhance the attach and update APIs to
>> set and modify the delete_on_termination flag.  The discrepancies in the
>> create and read operations calls into question whether the update change
>> should be on the PUT /servers API to match the server's read [6] or if
>> the os-volume_attachments update API should be modified to line up with
>> os-volume_attachments read.
>>
>>
>> [1]
>> http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
>> [2] http://developer.openstack.org/api-ref-compute-v2.1.html#attach
>> [3]
>>
>> https://ask.openstack.org/en/question/85242/the-api-action-attach-is-missing/
>> [4]
>>
>> https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/volumes.py#L318
>> [5]
>> http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
>> [6]
>> http://developer.openstack.org/api-ref-compute-v2.1.html#listDetailServers
>> [7]
>>
>> http://developer.openstack.org/api-ref-compute-v2-ext.html#deleteVolumeAttachment
>> [8]
>>
>> https://blueprints.launchpad.net/nova/+spec/delete-on-termination-modification
>>
>>
>>
>> __
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe:
>> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>>
> Several of the different paths you're pointing out are v2 legacy (e.g.
> anything with *-v2-ext.html). Anything with v2.1 is, well, the v2.1 API and
> is current.
>
> The code is very similar in most cases between v2 and v2.1. The main
> differences with v2.1 are (1) jsonschema validation on the front-end and
> (2) microversion support. More info is here [1].
>
> As for docs, there are a lot of missing docs or incorrect docs in the
> compute API. There is an etherpad [2] on gaps to fill there, patches are
> welcome.
>
> [1] http://docs.openstack.org/developer/nova/#compute-api-references
> [2] https://etherpad.openstack.org/p/nova-v2.1-api-doc
>
> --
>
> Thanks,
>
> Matt Riedemann
>
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova] Volume attachment APIs CRUD inconsistencies

[Anne Gentle]

On Fri, Dec 11, 2015 at 8:38 PM, Anne Gentle <annegen...@justwriteclick.com>
wrote:

>
>
> On Fri, Dec 11, 2015 at 7:33 PM, Matt Riedemann <
> mrie...@linux.vnet.ibm.com> wrote:
>
>>
>>
>> On 12/11/2015 1:48 PM, Sam Matzek wrote:
>>
>>> The CRUD operations for Nova volume attachments have inconsistencies
>>> between documentation and implementation.  Additionally, the read/get
>>> operation is implemented twice under different URIs.  What is Nova's
>>> direction for volume attachment APIs and how should the following
>>> discrepancies be resolved?
>>>
>>> The current state of affairs is:
>>> CREATE (volume attach) is documented twice under two different URIs: [1]
>>> and [2], but only os-volume_attachments [1] is implemented [3].
>>>
>>
> Matt, can you look a little deeper into what happened to
> os-volume_attachments? I'm worried we've missed one of the extensions.
>
> As for the docs, I thought we put in redirects from v2 to v2.1 but I need
> to investigate.
>
>
And to answer my own question, yes, line 226 of the Etherpad indicates that
doc is missing. Easy enough to add if anyone wants to grab a low-hanging
(read:easy) patch.

I'm going to hold off on the redirects until much more of that Etherpad
indicates cleanup.

Anne


> Anne
>
>
>> Attach volume as an action on the servers URI appears to have been part
>>> of the Nova V3 API, but its implementation no longer exists.
>>> Is it the future direction to have volume attach and detach done as
>>> server actions?
>>>
>>> READ is implemented twice and documented twice under two different URIs:
>>> os-volume_attachments [5] and server details [6]
>>> The two implementations do not return the same information and the only
>>> bit of information that is common between them is the volume ID.
>>> Why do we have two implementations and is one preferred over the other?
>>> Should one be deprecated and eventually removed with all enhancements
>>> going into the other?
>>>
>>> UPDATE is implemented [4] but not documented.
>>>
>>> DELETE (detach) only appears to be implemented and documented once: [7]
>>>
>>> A blueprint proposal exists [8] to enhance the attach and update APIs to
>>> set and modify the delete_on_termination flag.  The discrepancies in the
>>> create and read operations calls into question whether the update change
>>> should be on the PUT /servers API to match the server's read [6] or if
>>> the os-volume_attachments update API should be modified to line up with
>>> os-volume_attachments read.
>>>
>>>
>>> [1]
>>> http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
>>> [2] http://developer.openstack.org/api-ref-compute-v2.1.html#attach
>>> [3]
>>>
>>> https://ask.openstack.org/en/question/85242/the-api-action-attach-is-missing/
>>> [4]
>>>
>>> https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/volumes.py#L318
>>> [5]
>>> http://developer.openstack.org/api-ref-compute-v2-ext.html#attachVolume
>>> [6]
>>>
>>> http://developer.openstack.org/api-ref-compute-v2.1.html#listDetailServers
>>> [7]
>>>
>>> http://developer.openstack.org/api-ref-compute-v2-ext.html#deleteVolumeAttachment
>>> [8]
>>>
>>> https://blueprints.launchpad.net/nova/+spec/delete-on-termination-modification
>>>
>>>
>>>
>>>
>>> __
>>> OpenStack Development Mailing List (not for usage questions)
>>> Unsubscribe:
>>> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>>
>>>
>> Several of the different paths you're pointing out are v2 legacy (e.g.
>> anything with *-v2-ext.html). Anything with v2.1 is, well, the v2.1 API and
>> is current.
>>
>> The code is very similar in most cases between v2 and v2.1. The main
>> differences with v2.1 are (1) jsonschema validation on the front-end and
>> (2) microversion support. More info is here [1].
>>
>> As for docs, there are a lot of missing docs or incorrect docs in the
>> compute API. There is an etherpad [2] on gaps to fill there, patches are
>> welcome.
>>
>> [1] http://docs.openstack.org/developer/nova/#compute-api-references
>> [2] https://etherpad.openstack.org/p/nova-v2.1-api-doc
>>
>> --
>>
>> Thanks,
>>
>> Matt Riedemann
>>
>>
>> __
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe:
>> openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
>
> --
> Anne Gentle
> Rackspace
> Principal Engineer
> www.justwriteclick.com
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [nova][doc][tempest] How to handle HTTP203

[Anne Gentle]

On Mon, Dec 7, 2015 at 11:07 PM, Ken'ichi Ohmichi <ken1ohmi...@gmail.com>
wrote:

> Hi,
>
> Today, we have virtual API document sprint and we are facing a problem
> related to HTTP203 (Non-Authoritative Information).
> The api-site(http://developer.openstack.org/api-ref-compute-v2.1.html)
> contains HTTP203 as one of valid status codes for each API operation,
> but nova implementation code doesn't contain the status code and
> invalid from some nova developers' viewpoints.
>
> In addition, tempest also doesn't consider HTTP203 cases at all now.
> If nova returns HTTP203 response, tempest consider the response as
> invalid on its own tests.
>
> I am imaging this status code comes intentionally for proxying thing,
> so I feel it is nice to keep HTTP203 description in the api-site.
> If so, I would be nice to have a gate job which makes HTTP203 cases
> and tempest needs to be updated for covering these cases.
>

Interesting. I recently went through all the WADL because they had 200 203
in combination, and separated out all the 203 into separate responses. This
change was helpful for ensuring the accuracy of the future migration of the
docs. The 203 codes were from the Compute API specs originally written 5
years ago, and then as people copied from Compute the 203 spread.

I think what you're saying is that providers could use a 203 for some use
case, but a proxy server would have to provide the 203?

Anne




>
> Any comments are welcome.
>
> Thanks
> Ken Ohmichi
>
> __
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [all] [release] New Mitaka release schedule page

[Anne Gentle]

On Mon, Dec 7, 2015 at 4:35 PM, Anita Kuno <ante...@anteaya.info> wrote:

> On 12/04/2015 05:50 AM, Thierry Carrez wrote:
> > Hi everyone,
> >
> > As part of the effort to move reference information off the wiki to a
> > more peer-reviewable area, the Mitaka release schedule page was moved to:
> >
> > http://docs.openstack.org/releases/schedules/mitaka.html
> >
> > One side benefit is that projects can propose and add their own
> > deadlines (think spec submission deadline, early feature freezes, etc.)
> > to this page by proposing changes to the doc/source/schedules/mitaka.rst
> > file in the openstack/releases git repository:
> >
> >
> http://git.openstack.org/cgit/openstack/releases/tree/doc/source/schedules/mitaka.rst
> >
> > Ideally that way it will turn into a clear list of all development
> > deadlines in a given development cycle, making it easier to keep track
> > of everything.
> >
> > Please help by adding your own project information to this page!
> > Cheers,
> >
>
> This looks great, thanks Thierry.
>
> I often use the release schedule to reference the upcoming summit, so
> Austin in this case. Any thoughts on when we can expect an n.rst file in
> /releases? Any objection to me offering one up if only to put in the
> Austin summit dates?
>

And, in the opposite timeline direction, I was hoping for the list of
releases and links to release notes from before Mitaka. Okay if I propose a
standalone RST file that gathers those from the original wiki page?
Anne


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



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] openstackdocstheme to be considered (very) harmful for your generated sphinx docs

[Anne Gentle]

On Mon, Dec 7, 2015 at 8:04 AM, Morgan Fainberg <morgan.fainb...@gmail.com>
wrote:

>
>
> On Mon, Dec 7, 2015 at 7:54 AM, Thomas Goirand <z...@debian.org> wrote:
>
>> On 12/04/2015 03:23 PM, Anne Gentle wrote:
>> >
>> >
>> > On Fri, Dec 4, 2015 at 8:09 AM, Thomas Goirand <z...@debian.org
>> > <mailto:z...@debian.org>> wrote:
>> >
>> > Hi,
>> >
>> > I've investigated a bit the openstackdocstheme, and tried to remove
>> some
>> > of the (numerous) javascript with external references. And it's
>> *very*
>> > ugly: it's full of google stuff, random CDN and so on.
>> >
>> >
>> > I absolutely want to address these concerns.
>>
>> Hi,
>>
>> Thanks for replying.
>>
>> Let me start by this. In Debian, I'm adding this patch:
>>
>>
>> http://anonscm.debian.org/cgit/openstack/python-openstackdocstheme.git/tree/debian/patches/patch-out-external-references.patch
>>
>> Now, let me explain why.
>>
>> > Let's start with making sure I understand the concerns so we can start
>> > tracking the work requirements with bugs.
>> >
>> > 1. Google stuff, considered non-free. Can you list specifics? Fonts and
>> > analytics js for starters, let me know if there are others?
>>
>> It's not only about non-freeness, it's also about the fact that I don't
>> want Google to know when I'm browsing my local hard drive HTML, which it
>> would when browsing any OpenStack docs generated by OpenStack packages
>> in Debian, without the Debian patch to openstackdocstheme.
>>
>> Also, look at this from
>> openstackdocstheme/theme/openstackdocs/script_footer.html (@@ -50,17
>> +50,3 @@ in my patch):
>>
>> gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
>>
>> Well, if I'm using file:// to browse some HTML docs, then it's going to
>> fetch www.google.com/cse/cse.js over a non SSL connection. That's a
>> security issue.
>>
>> I believe there is the same issue with google analytics.
>>
>> > 2. Random CDN: maxcdn, which was provided to us by the Foundation's web
>> > designer who gave us the design. We need CDN for performance reasons.
>> > What CDN meets your requirements?
>>
>> Users browsing the local hard drive documentation don't want to access
>> an external resource, even on a CDN. It would even be slower.
>>
>> The idea to speed-up browsing on the openstack.org is a very good one,
>> and I salute the effort to use such a CDN. But let's not forget that the
>> generated docs also end up in the distribution FOO-doc packages.
>>
>>
> I think that this falls into the category that we need a way to add in the
> CDN information for the related resources when generating the docs. The
> publish job that pushes this data up to the actual websites can handle the
> toggling this change. This should totally be both reasonable and accepted
> (will require an infra change as well long term). I agree that the use of
> the CDN for local docs is not the right choice. Clearly this is a
> bug/enhancement that should be made.
>
>
>> > 3. Non-minified JS, being worked on two bugs now. [1] [2]
>> >
>> > Does that list capture your "ugly" claim in a measureable manner?
>> >
>> > [1]  https://bugs.launchpad.net/openstack-manuals/+bug/1501641
>> > [2]  https://bugs.launchpad.net/openstack-manuals/+bug/1502806
>> >
>> > Not only this, but generated docs could potentially do call some of
>> > these objects without using HTTPS (which is the case when browsing a
>> > local *-doc package generated sphinx document using file://).
>> >
>> > Could you list the calls in a bug please? That will help with triaging.
>>
>> Well, last time I opened such a bug, it was closed and tagged "wontfix",
>> and my patch was voted out. On patch [1], it was marked as low priority
>> as well. I've seen no activity on #1502806 for a month and a half too.
>
>
>> If I open such bugs again, will there be actions on them?
>>
>> > At the present moment, I would recommend projects to *not* use the
>> > openstackdocstheme at all until all of this is fixed.
>> >
>> >
>> > I'd like to understand your concerns further and specifically before
>> > taking this type of action.
>> >
>> > I'm also thinking: am I the only one in this community that cares
>> about
>> > browsing privacy?
>> &g

Re: [openstack-dev] openstackdocstheme to be considered (very) harmful for your generated sphinx docs

[Anne Gentle]

On Mon, Dec 7, 2015 at 8:25 AM, Jeremy Stanley <fu...@yuggoth.org> wrote:

> On 2015-12-07 09:04:20 -0500 (-0500), Morgan Fainberg wrote:
> [...]
> > * We should not (regardless of free/non-free/etc) make sure that the docs
> > are fully self-contained when built locally. This would address the
> privacy
> > and security issues for the local docs. (Again Analytics can be enabled
> as
> > a build-time job).
>
> Assuming s/not// (looks like a typo?) I'm in complete agreement.
>
> > * We should ensure we are only loading any external sources via HTTPS
> > rather than HTTP.
>
> Or better yet, not loading any external sources at all (though
> figuring out how to find and link to locally installed distro
> packages of fonts and similar resources might get complicated, and
> so may still be easier left as distro-specific patches in their
> respective packaging).
>

Okay, this is helpful because even after logging the bugs for upstream I'm
not exactly sure how the offline use case becomes a reality. As an upstream
team our first priority is online.

Thanks,
Anne


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



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] Documentation containing external resource links & privacy breaches

[Anne Gentle]

On Mon, Dec 7, 2015 at 3:18 PM, Cory Benfield <c...@lukasa.co.uk> wrote:

>
> > On 7 Dec 2015, at 18:37, Thomas Goirand <z...@debian.org> wrote:
> >
> >
> > The reason why I'd like an env var, is that I could simply modify
> > openstack-pkg-tools (which is included in every debian/rules) to set
> > that variable once and for all. For example, just adding in
> > openstack-pkt-tools's pkgos.make:
> >
> > export OPENSTACKDOCSTHEME_SELF_CONTAINED=yes
> >
> > would do the trick for all my packages.
> >
> > Your thoughts?
>
> I am open to having such an environment variable that would control *all*
> documentation or theme related external properties, not just Google
> Analytics, but I’m also not a core on the openstackdocstheme project. ;)
>

One idea to consider, rather than all this extra configuration work can you
use one of the themes that ships with Sphinx for local builds?
Anne




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


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev