Open Stack

Thanks Karen for looking into this and working up examples.

On Fri, Jun 17, 2016 at 10:15 AM, Karen Bradshaw <kbhawkey at gmail.com> wrote:
> Hi all.
> I've been thinking about how to present the API References/Guides from
> developer.openstack.org and how to customize components from the
> openstackdocstheme for the API References/Guides.
>
> So far, two options come to mind for updating developer.openstack.org:
> -Add links (add new icons for each service?) to developer.openstack.org for
> each published API Reference and Guide.  I think this is preferred as all
> references are displayed at the same time.

I hope that Marcela Bonell can work something like this solution into
the developer.openstack.org landing page design. Copying her on my
reply here, as I don't know if she's subscribed to this mailing list.

> -Add a single drop down menu, listing the APIs/Guides.

Yep, this is also needed from each page built from a guide or reference.

>
> Customizing openstackdocstheme library:
> - Add new drop down menu which lists the published api references and
> guides, replacing the current sidebartoc.  This menu is configurable.

Yeah, this sounds good (and I like your start!)

> - Add new navigation bar near/replacing existing next/prev/bug navigation
> bar.

This idea is interesting! Good thinking.

>   The new navigation bar could contain links to the developer docs/the guide
> for        this service/what's on this page/bug input.  Also configurable.
> Some initial work at, https://review.openstack.org/#/c/329508

Thanks! Commented on that review as well.

>
> Some remaining questions about how to get a link to the content of the
> latest published api references/guides.  I imagine it would be best if the
> build of the osdocstheme library was not coupled with a static list of
> published references.
> How can/should this list be generated to manage the published references?

I have been webscraping the current docs.openstack.org/developer sites
to try to get a sense of how many projects are not currently using the
YAML plus RST approach. I've also been trying to get a handle on how
many of the 50+ projects need REST API reference docs. I abandoned a
tag-based approach in https://review.openstack.org/#/c/317094/. I'm
still working on https://review.openstack.org/#/c/316396/ where I'll
expand from contributor docs to REST API docs.

All that to say, here's a list of scraped API references, some of
which aren't really relevant to end-users, such as oslo library API
docs.

http://paste.openstack.org/show/520952/

But, of course, unless a project uses the new theme, they can't be
included in the list of published references. I think this approach
works well to ensure that the end-user REST API experience is
consistent across OpenStack.

> Also, each published API Reference could build with the openstackdocstheme
> so that the references,
> 1) look similar
> 2) have a menu to toggle between references
> Other ideas?

I think you're off to a great start and I'll keep reviewing your
ideas! Thanks a bunch.
Anne

> Thanks,
> Karen
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
www.justwriteclick.com