[OpenStack-docs] Api Ref links/openstackdocs theme
annegentle at justwriteclick.com
Tue Jun 21 15:08:48 UTC 2016
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
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
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.
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
More information about the OpenStack-docs