Open Stack

Just a couple notes about #5 (inking to WADL files in separate repositories):


  1.  This feature in supported in version 1.10.0 of the clouddocs maven plugin, which has now been reverted back to 1.9.3 due to request/response issues. You should be able to test using 1.9.4-SNAPSHOT until version 1.10.0 is available again.
  2.  You must use a plain URL to access the wadl. See the following example.

For example, to get the plain version for the following URL:

http://git.openstack.org/cgit/openstack/api-site/tree/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl

Browse to the above location in Firefox, and then click (plain<http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl>) on the blob: line, just above where the wadl text appears.

This will display the plain version of the URL:

http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl

Then use the plain version of the URL to access the wadl resources in the API Devguide:


<wadl:resources
            href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl"
            xmlns:wadl="http://wadl.dev.java.net/2009/02"/>

Mike

From: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>
Reply-To: OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Date: Wednesday, September 18, 2013 8:36 PM
To: "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>, OpenStack Development Mailing List <openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>>
Cc: Glen Campbell <glen.campbell at RACKSPACE.COM<mailto:glen.campbell at RACKSPACE.COM>>
Subject: [openstack-dev] What's Up Doc? Sep 18 2013


Less than a month until the Oct. 17th timed release! We're in better shape than in past releases but the install guide consolidation is crucial and there are many doc bugs. It's crunch time!

1. In review and merged this past week:

Congrats to Michael Still for his first doc patches to openstack-manuals! He got his new skillz at boot camp. Thanks for the patches!

I see good doc bug fixes going in, and Tom put in an update to the auto-generated tables.

We had a lot of cleanup to do for the flattening of directories but I think it has mostly settled now. The last step is to move the Networking Admin Guide's content into the correct locations (install or config or admin). Nermina's on it, assigned to bug  https://bugs.launchpad.net/openstack-manuals/+bug/1223542.

Andreas has a good Etherpad going to talk about continuous publishing: https://etherpad.openstack.org/Continous_Publishing. It's possible we'll need to release the Cloud Admin Guide as well due to many references to configuration files. Please join in the discussion as we only have less than a month until release!

2. High priority doc work:

The install guide remains a high priority as do doc bugs. Shaun is working on a patch this week to consolidate the basic-install to create one single-sourced install-guide (which will document for yum, apt, and zypper). There were over 300 doc bugs in openstack-manuals earlier this week as some docimpact bugs got logged, but we are making decent progress.

We also need to have someone re-run the autodoc tables and try to match up with some of the storage patches in this week: https://review.openstack.org/#/c/47044/ and https://review.openstack.org/#/c/47118/.

3. Doc work going on that I know of:

Kersten Richter is working on the Compute API docs again and getting an environment set up.

4. New incoming doc requests:

At the Doc Boot Camp, Joe Gordon asked me to write up a checklist of sorts for what info should go along with a DocImpact flag. I wrote up my ideas in a blog post and would love more input before putting it on the wiki.

http://justwriteclick.com/2013/09/17/openstack-docimpact-flag-walk-through/

5. Doc tools updates:

We had a 1.10.0 release today but had to revert back to 1.9.3 due to the request/responses not appearing in the API reference page. David Cramer's aware of the problem and will work through it.

We also had a breakthrough where we can now link to WADL files in separate repositories so we have a single source of truth. Thanks to Mike Asthalter for testing! He reported that you can use this syntax in the xml doc where you want to refer to the WADL:

<wadl:resources
            href="http://git.openstack.org/cgit/openstack/api-site/plain/api-ref/src/wadls/orchestration-api/src/v1/orchestration-api.wadl"
            xmlns:wadl="http://wadl.dev.java.net/2009/02"/>

6. Other doc news:

We had a great time at Docs Boot Camp. I wrote up a blog entry and posted some pictures:

http://justwriteclick.com/2013/09/13/openstack-docs-boot-camp-wrap-up/

https://plus.google.com/photos/107069996006011564519/albums/5922817305073319953?authkey=CN6V5c_Aq_9w

Super happy to see both VMWare and RedHat hiring upstream OpenStack writers!

http://jobs.redhat.com/jobs/descriptions/technical-writer-brisbane-queensland-australia-job-1-3925604<http://www.linkedin.com/redir/redirect?url=http%3A%2F%2Fjobs%2Eredhat%2Ecom%2Fjobs%2Fdescriptions%2Ftechnical-writer-brisbane-queensland-australia-job-1-3925604&urlhash=XXzf>

http://jobs.vmware.com/job/Palo-Alto-Sr_-Technical-Writer%2C-OpenStack-Job-CA-94301/7043400/<http://www.linkedin.com/redir/redirect?url=http%3A%2F%2Fjobs%2Evmware%2Ecom%2Fjob%2FPalo-Alto-Sr_-Technical-Writer%252C-OpenStack-Job-CA-94301%2F7043400%2F&urlhash=ZeSC>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130919/6a65eed1/attachment.html>