Open Stack

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>
 To: "openstack-docs at lists.openstack.org" <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,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
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.html>