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

Anne Gentle annegentle at justwriteclick.com
Thu Jun 9 14:47:38 UTC 2016


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/<service> and
developer.openstack.org/api-guide/<service>.

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160609/445ac3cf/attachment.html>


More information about the OpenStack-dev mailing list