Open Stack

On 07/12/2015 01:48 AM, Anne Gentle wrote:
>
>
> On Sat, Jul 11, 2015 at 2:35 PM, Andreas Jaeger <aj at suse.com
> <mailto: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>
>         <mailto: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?

Only reused if all the headers in the file will we at the same heading 
level in each inclusion. Meaning.

You cannot do:

Some header with second-level heading
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:include:...

as well as:

Some other header with third-level-heading
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:include:...

if your include file includes headers since include is a *verbatim* 
include and not a reference.

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

Just grep for ":hidden:" to find the hidden toc trees. 
admin-guide-cloud-rst currently has four of them and there are two in 
the install-guide-rst directory.

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

My preference:
Use tocdirs and reference the files from there, includes should be only 
used for duplicated content but not to split up large files. For 
splitting up large files, use a proper table of content. If a file is 
large in source, it will be large in HTML as well, so proper structuring 
needs to be thought about

Includes should be only used for duplicated test that shows up in 
several places. I like how it's done in 
https://review.openstack.org/#/c/196890/ for the smaller files. I'm not 
sure about the 350 lines of duplication.

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

I think we should use them for smaller duplicate text but not to split a 
large file into smaller ones.

> Those are my questions for now, thanks for the quick response.

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