Open Stack

Why can't we use the standard Sphinx xref tools for links to this frequently-used information?
http://sphinx-doc.org/markup/inline.html
  
It's pretty easy for docs in the same repo.  I've heard that there is a way to implement this fordocs in different repos but I don't have experience with that.

meg

      From: Anne Gentle <annegentle at justwriteclick.com>
 To: Karen Bradshaw <kbhawkey at gmail.com> 
Cc: Andreas Jaeger <aj at suse.com>; "openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org> 
 Sent: Monday, April 6, 2015 8:36 AM
 Subject: Re: [OpenStack-docs] tables, figures, appendix A
   


On Mon, Apr 6, 2015 at 10:28 AM, Karen Bradshaw <kbhawkey at gmail.com> wrote:

Hi.  I do not have an opinion about including the tables and figures.Just checking on what should be included or not.

So far we are reviewing with a convention that we don't have captions on figures or labels on tables. (Ha! That rhymes.) Let's stick with that convention. 
The links provide another navigation point into the documentation.For information that is used frequently, say a common installation routine or API commands, a link may be useful.

Agreed, but I don't know how to make those with Sphinx right now, so at this point in the migration we won't plan on doing those. 
I can try and do the initial conversion of app_support.xml to user-guides/source/common/app_support.rst?  Where would this file be included, under indices and tables in index.rst and index-admin.rst?

Yep, you got it!
Anne 
-Karen
On Mon, Apr 6, 2015 at 10:54 AM, Anne Gentle <annegentle at justwriteclick.com> wrote:



On Mon, Apr 6, 2015 at 9:48 AM, Andreas Jaeger <aj at suse.com> wrote:

On 04/06/2015 03:38 PM, Karen Bradshaw wrote:

Hi. I am reviewing the new content generated for the admin user guide.


thanks!


Is there a plan to add an appendix for community support information?


IMHO it would be great to have it. Do you want to convert it?

Please do add it. If you can't convert it, just let me know and I'll do it. 



How about adding labels for the tables and figures?


If we do this, let's write it down on our markup conventions page as well. I'm not feeling strongly either right now,



Currently our convention for RST markup is to only use the image directive. We'd have to start using the figure directive in order to get a caption for each figure. 
https://wiki.openstack.org/wiki/Documentation/Markup_conventions#Image is where the convention is documented. 

For tables, I'm not aware of a way to ensure a caption is used, other than to put it in our conventions as a paragraph before the table. 
With the migration goal of simplifying and welcoming more contributors, it seems a little heavy-handed to require captions for tables and figures. So I want to hear why we would require them other than "we've done it that way before." Any thoughts? I can't justify the overhead when we aren't doing collections of them in the new world. Any other thoughts? 
Thanks,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, Jennifer Guild, Dilip Upmanyu,
       Graham Norton, HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126


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






-- 
Anne Gentle
annegentle at justwriteclick.com





-- 
Anne Gentle
annegentle at justwriteclick.com
_______________________________________________
OpenStack-docs mailing list
OpenStack-docs at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


   
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150406/d3828c97/attachment.html>