Open Stack

On 07/14/2015 10:55 PM, Lana Brindley wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 12/07/15 18:34, Andreas Jaeger wrote:
>> Lana, Anne, thanks for the feedback.
>>
>> Here's a reworked proposal,
>>
>> Andreas
>>
>> RST include file policy
>>
>> Include files using the ":include:" directive should be used for
>> smaller content that is duplicated in several files (note that this
>> is something that should be avoided in general).
>>
>> For include files, give the files the suffix ".txt" instead of the
>> usual ".rst".
>>
>> Note that when including files that use headings for section
>> structure, the master file needs to include it at the same level
>> since heading markup is not relative.
>>
>> For structuring files, split them up and use a toctree to reference
>> the files. If files get too large, it is often a sign that the
>> information is not presented properly and therefore the file should
>> be reworked instead of split artifically in smaller files using
>> includes.
>>
>> Files can be shared between guides as separate top-level files,
>> like it's done for glossary and support appendix already.
>>
>
> +1
>
> Nice work, Andreas :)

Added as 
https://wiki.openstack.org/wiki/Documentation/Structure#RST_include_file_policy

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, Dilip Upmanyu, Graham Norton,
        HRB 21284 (AG Nürnberg)
     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126