Open Stack

On Sat, Jul 11, 2015 at 2:35 PM, Andreas Jaeger <aj at suse.com> wrote:

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


Yep, I know what ugliness you mean. :)


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

By "might not be reused" do you mean should not be reused at all, or only
reused if all the headers in the file will be at the same heading level in
each inclusion?

I haven't studied the plans for the user guide/ admin guides re-works to
know if there will be much of this.


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


So, best practice, stop duplicating content? Or avoid includes always? I'd
lean towards flatter less book-ish structures myself but I don't know how
things are looking for the re-architecting. Looking at
http://specs.openstack.org/openstack/docs-specs/specs/liberty/reorganise-user-guides.html
we may need to avoid includes?

Those are my questions for now, thanks for the quick response.
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, Dilip Upmanyu, Graham Norton,
>        HRB 21284 (AG Nürnberg)
>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
>
>


-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150711/5f3f4bf0/attachment.html>