Open Stack

One question and one comment/question...
I know of another include method, which is:
.. include:: /<path-from-top-of-repository>/<filename>.rst

What are the relative merits of this method to others?

Also a caveat about reusing included files...  If a file includes a referencing tag (that's an RST tag),it can only be included in one location in the repo or the build fails -- unless someone knows a cleverwork-around.
To explain, a file might code a section like:
.. _ntp-setup:
Setting up NTP~~~~~~~~~~~~
Another file could then reference this section as a link like this:
See :ref:`ntp-setup` for instructions.
I'm thinking that the NTP setup instructions are probably the same for Ubuntu, RHEL, et cetera, so thisis a perfect candidate for having a common source file.
I think it might work if the tag is coded in the include'ing file:
.. _ntp-setup-ubuntu:
<include statement>
I don't know if this works with all include methods -- this should be considered because, I think as we moveforward, we will be needing to do more cross-referencing within the docs.
meg

 
      From: Andreas Jaeger <aj at suse.com>
 To: Matt Kassawara <mkassawara at gmail.com> 
Cc: "openstack-docs at lists.openstack.org" <Openstack-docs at lists.openstack.org> 
 Sent: Tuesday, July 14, 2015 7:11 AM
 Subject: Re: [OpenStack-docs] RST include files - proposal forward
   
On 07/14/2015 03:51 PM, Matt Kassawara wrote:
> On includes...
>
> Using includes within a guide make sense for repeating content. However,
> I'm not sure how much content meets this qualification outside of a few
> sections in the networking guide. The ability to reuse command (CLI)
> output increases consistency, reduces errors, and may also hasten
> updates when commands decide to change flags and/or output. On the other
> hand, it makes contributions (particularly for new folks) a bit more
> interesting. Let's decide if we want to use includes or not (perhaps try
> them in the networking guide?)... and if so, decide on how to make them
> work best technically.
>
> On structure...
>
> I prefer the single large HTML file with anchors for the following reasons:
>
> 1) Easier navigation due to shallower structure (lack of pages mostly
> consisting of links to other sections).
> 2) Easier string searches with all content for a topic on a single page
> (EPPO?).

But it covers many different topics, some not even really related 
(besides it's all Identity)

> 3) Fewer issues with deep linking by search engines and people to
> specific HTML filenames. Links to missing anchors simply redirect to the
> top of the page rather than 404.


So, what are you saying to my reviews?

Those files should include the content directly instead of using the 
include instruction?

Or the files are fine as is?

Thanks for looking into this,
Andreas

> On Sun, Jul 12, 2015 at 3:34 AM, Andreas Jaeger <aj at suse.com
> <mailto:aj at suse.com>> wrote:
>
>    Btw. I think we misused the include when converting. We now have
>    files that are very large HTML files but were separate before.
>
>    Have a look at:
>    https://review.openstack.org/#/c/200869/
>    and compare the new content:
>    http://docs-draft.openstack.org/69/200869/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/1c963f7//publish-docs/draft/admin-guide-cloud-rst/orchestration.html
>
>    the old docbook one:
>    http://docs.openstack.org/admin-guide-cloud/content/ch_admin-openstack-orchestration.html
>
>    and the current converted one where everything is on a single page:
>    http://docs.openstack.org/draft/admin-guide-cloud-rst/orchestration.html
>
>
>    Similar check the Identity chapter in current RST where everything
>    is a single page:
>    http://docs.openstack.org/draft/admin-guide-cloud-rst/identity_management.html#use-trusts
>
>    and compare with the DocBook
>    http://docs.openstack.org/admin-guide-cloud/content/ch-identity-mgmt-config.html
>
>    And then check my proposed change:
>    https://review.openstack.org/200874
>
>    and look at the html:
>    http://docs-draft.openstack.org/74/200874/1/check/gate-openstack-manuals-tox-doc-publish-checkbuild/9ee3f7e//publish-docs/draft/admin-guide-cloud-rst/identity_management.html
>
>
>    Andreas
>    --
>      Andreas Jaeger aj@{suse.com <http://suse.com>,opensuse.org
>    <http://opensuse.org>} Twitter/Identica: jaegerandi
>        SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>        GF: Felix Imendörffer, Jane Smithard, 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
>    <mailto:OpenStack-docs at lists.openstack.org>
>    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


>


-- 
  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, 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

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