Open Stack

On 21/06/15 02:58, Olena Logvinova wrote:
> Good Saturday to everyone!
> 
> Thanks Andreas for opening this topic. And thanks much Meg for such a
> detailed answer!
> 
> I agree with Meg here + another argument to have small children files
> that are logical sub-sections of 1 chapter: it's much easier to review
> and merge these in comparison with 200-300 lines' looong memoirs. I
> prefer files no longer than 100-150 lines. But I will gladly hear out
> other ideas on this matter. 

Generally agree with Lena and Meg here - I also prefer child file
inclusions, with files of a size that makes sense for how they are used.

I found this in the sphinx docs, which might let us use simple include
statements without worrying about the hidden toctree every time:

"""
In cases where you want to have only one top-level toctree and hide all
other lower level toctrees you can add the “includehidden” option to the
top-level toctree entry:

.. toctree::
   :includehidden:
"""

I guess that can also be overridden by explicitly making another toctree
in a child file if we did want one.

Does that work?


> Best
> Lena
> 
> On Sat, Jun 20, 2015 at 3:00 PM,
> <openstack-docs-request at lists.openstack.org
> <mailto:openstack-docs-request at lists.openstack.org>> wrote:
> 
>     Send OpenStack-docs mailing list submissions to
>             openstack-docs at lists.openstack.org
>     <mailto:openstack-docs at lists.openstack.org>
> 
>     To subscribe or unsubscribe via the World Wide Web, visit
>            
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>     or, via email, send a message with subject or body 'help' to
>             openstack-docs-request at lists.openstack.org
>     <mailto:openstack-docs-request at lists.openstack.org>
> 
>     You can reach the person managing the list at
>             openstack-docs-owner at lists.openstack.org
>     <mailto:openstack-docs-owner at lists.openstack.org>
> 
>     When replying, please edit your Subject line so it is more specific
>     than "Re: Contents of OpenStack-docs digest..."
> 
> 
>     Today's Topics:
> 
>        1. Re: RST conversion and file splits ? (Meg McRoberts)
> 
> 
>     ----------------------------------------------------------------------
> 
>     Message: 1
>     Date: Fri, 19 Jun 2015 20:59:19 +0000 (UTC)
>     From: Meg McRoberts <dreidellhasa at yahoo.com
>     <mailto:dreidellhasa at yahoo.com>>
>     To: Andreas Jaeger <aj at suse.com <mailto:aj at suse.com>>,
>             "openstack-docs at lists.openstack.org
>     <mailto:openstack-docs at lists.openstack.org>"
>             <openstack-docs at lists.openstack.org
>     <mailto:openstack-docs at lists.openstack.org>>
>     Subject: Re: [OpenStack-docs] RST conversion and file splits ?
>     Message-ID:
>            
>     <1002285246.2547175.1434747559361.JavaMail.yahoo at mail.yahoo.com
>     <mailto:1002285246.2547175.1434747559361.JavaMail.yahoo at mail.yahoo.com>>
>     Content-Type: text/plain; charset="utf-8"
> 
>     I do not thoroughly grok the intricacies of toctree --I just try to
>     follow whatsomeone else does and hope it doesn't blow up on me ;-)
>     However, it sounds like you are musing about issues of source file
>     structureand I have been thinking about that a bit.? It sounds like
>     you are thinking abouthaving one big file per "topic".? I have
>     worked with people who argue that nodoc source file should have more
>     than one heading in it -- each subsectiongets its own file.? My own
>     preferences fall somewhere in the middle, but findingthe "sweet
>     spot" between the two is non-trivial.
>     The great advantage of having smaller files is that different people
>     can work ondifferent sections at the same time without causing
>     horrific 6-way-merge scenarios.For example, in the new HA Guide, we
>     have a topic about configuring the controllernode for high
>     availability.? This has subtopics for pacemaker/corosync,
>     mysql/galera, rabbitmq,
>     HAProxy, keystone, et cetera.? The writers and reviewers for each of
>     these subsectionsare often different people, so having those
>     subtopics in different files that are includedin the larger topic
>     file has definite advantages.
>     I would advocate a less-flat directory structure for the source
>     files.? Our current practiceseems to be to give a common "front-end"
>     to all the subfiles for a topic, which causessome really long file
>     names; for example:
>     ???? controller-ha.rst???? controller-ha-pacemaker.rst????
>     controller-ha-galera.rst???? controller-ha-rabbitmq.rst
>     ???? controller-ha-haproxy.rst???? et cetera
>     It also makes for a very cluttered source directory.? Things would
>     be cleaner if we hadonly the controller-ha.rst file in the source
>     directory, with a controller subdirectory thathad files named
>     pacemaker.rst, galera.rst, rabbitmq.rst, haproxy.rst...
>     As appropriate, the subdirectory might have a subdirectory.? For
>     example, the galerasubtopic might have separate sections for MySQL
>     and MariaDB and maybe anotherdatabase or two.? Different people
>     might work on different database options, so havinga galera
>     subdirectory with different files for the different database
>     architectures makessense.
>     On the other hand, the haproxy subtopic might have sections for
>     install, configure, verify,launch.? I don't see much advantage in
>     breaking those up into separate files, although Iknow some people
>     who would advocate for that.
> 
>     In addition to breaking the files up for parallel development,
>     well-chosen discrete files cansimplify restructuring the material --
>     rather than having to yank 75 lines of doc source fromone file and
>     insert it into another, you can just move the inclusion line from
>     one topic fileto another and voila!
>     What does everyone else think?meg
> 
> 
>           From: Andreas Jaeger <aj at suse.com <mailto:aj at suse.com>>
>      To: "openstack-docs at lists.openstack.org
>     <mailto:openstack-docs at lists.openstack.org>"
>     <openstack-docs at lists.openstack.org
>     <mailto:openstack-docs at lists.openstack.org>>
>      Sent: Friday, June 19, 2015 11:40 AM
>      Subject: Re: [OpenStack-docs] RST conversion and file splits ?
> 
>     On 06/19/2015 02:36 PM, Andreas Jaeger wrote:
>     > With DocBook, we had often included one file from another - and used
>     > that included file only in a single place. So, there was no reason
>     to do
>     > it from an editors point of view, just splitting of content.
>     >
>     > Looking at https://review.openstack.org/#/c/192575/ I wonder
>     what's the
>     > right thing to do. The included file is not mentioned in a table of
>     > contents and thus we normally use ":orphan:" but this does not work
>     > here, so a hidden toctable is used.
>     >
>     > BUT why should we split this up in several files at all? If there's a
>     > toc table used - or the file is used in several places -, splitting it
>     > up is fine but just for inclusion I see no need for separate files.
>     >
>     > Or is there a preference for how large files are and how to split
>     them up?
>     >
>     > Is there any guidance we want to follow for file splits like these?
>     >
>     > Looking at the :orphan:/hidden toctable constructs, I'm against file
>     > splits and therefore ask to see whether we can reach some
>     consensus that
>     > I then follow in further reviews,
> 
>     Another example with the same problem:
> 
>     https://review.openstack.org/#/c/193518/2/doc/admin-guide-cloud-rst/source/blockstorage.rst
> 
> 
> 
>     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
> 
> 
> 
>     -------------- next part --------------
>     An HTML attachment was scrubbed...
>     URL:
>     <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150619/10e0cb74/attachment-0001.html>
> 
>     ------------------------------
> 
>     _______________________________________________
>     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
> 
> 
>     End of OpenStack-docs Digest, Vol 36, Issue 48
>     **********************************************
> 
> 
> 
> 
> -- 
> Best regards,
> Olena Logvinova,
> Technical Writer | Mirantis, Kharkiv | 38, Lenin av., Kharkiv
> ologvinova at mirantis.com <mailto:ologvinova at mirantis.com> | +380950903196
> <tel:%2B380950903196>
> 
> 
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>