Open Stack

On 07/11/2015 08:05 PM, Anne Gentle wrote:
>
>
> On Sat, Jul 11, 2015 at 12:56 PM, Andreas Jaeger <aj at suse.com
> <mailto:aj at suse.com>> wrote:
>
>     So far, we have included RST files with
>     :include: some-file.rst
>
>     and then added the file to a hidden toctree.
>
>     I propose - as mentioned by somebody else previously - to use the
>     following practice:
>
>     * include files end with .txt
>
>     That's all. Since sphinx ignores .txt files, we do not need to add
>     any hidden toctree at all...
>
>
> One potential benefit to keeping .rst is that they render okay (not
> great, I know) on GitHub itself. Basically .txt files with RST markup
> don't render at all.

With all these hidden tocentries, I consider inclusion of the RST some 
ugliness which we don't get with TXT files. It also makes it clear that 
TXT are included files.


> I've seen both practices so we should discuss, adopt one and stick with it.
> Thanks for bringing it up Andreas!

Btw. since we do not have <section> but headings with specific markup 
for each level, an include file with headings might not be reused in 
other places - only if it's at the same level of headings.

Thus, my preference would even be to avoid includes *unless* we need 
them for duplicate content. But so far I haven't seen any buy-in on 
this, so propose the above.

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