<html><body><div style="color:#000; background-color:#fff; font-family:HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif;font-size:16px"><div id="yui_3_16_0_1_1434657432445_657551" dir="ltr">I do not thoroughly grok the intricacies of toctree --I just try to follow what</div><div dir="ltr">someone else does and hope it doesn't blow up on me ;-)</div><div dir="ltr"><br></div><div dir="ltr">However, it sounds like you are musing about issues of source file structure</div><div id="yui_3_16_0_1_1434657432445_657553" dir="ltr">and I have been thinking about that a bit. It sounds like you are thinking about</div><div dir="ltr">having one big file per "topic". I have worked with people who argue that no</div><div dir="ltr">doc source file should have more than one heading in it -- each subsection</div><div id="yui_3_16_0_1_1434657432445_657943" dir="ltr">gets its own file. My own preferences fall somewhere in the middle, but finding</div><div id="yui_3_16_0_1_1434657432445_657945" dir="ltr">the "sweet spot" between the two is non-trivial.</div><div id="yui_3_16_0_1_1434657432445_657947" dir="ltr"><br></div><div id="yui_3_16_0_1_1434657432445_657949" dir="ltr">The great advantage of having smaller files is that different people can work on</div><div id="yui_3_16_0_1_1434657432445_658262" dir="ltr">different sections at the same time without causing horrific 6-way-merge scenarios.</div><div id="yui_3_16_0_1_1434657432445_657942" dir="ltr">For example, in the new HA Guide, we have a topic about configuring the controller</div><div id="yui_3_16_0_1_1434657432445_657933" dir="ltr">node for high availability. This has subtopics for pacemaker/corosync, mysql/galera, rabbitmq,<br></div><div id="yui_3_16_0_1_1434657432445_657952" dir="ltr">HAProxy, keystone, et cetera. The writers and reviewers for each of these subsections</div><div id="yui_3_16_0_1_1434657432445_657954" dir="ltr">are often different people, so having those subtopics in different files that are included</div><div id="yui_3_16_0_1_1434657432445_657958" dir="ltr">in the larger topic file has definite advantages.</div><div id="yui_3_16_0_1_1434657432445_658000" dir="ltr"><br></div><div id="yui_3_16_0_1_1434657432445_658265" dir="ltr">I would advocate a less-flat directory structure for the source files. Our current practice</div><div id="yui_3_16_0_1_1434657432445_658267" dir="ltr">seems to be to give a common "front-end" to all the subfiles for a topic, which causes</div><div id="yui_3_16_0_1_1434657432445_658269" dir="ltr">some really long file names; for example:</div><div id="yui_3_16_0_1_1434657432445_658271" dir="ltr"><br></div><div id="yui_3_16_0_1_1434657432445_658273" dir="ltr"> controller-ha.rst</div><div id="yui_3_16_0_1_1434657432445_658275" dir="ltr"> controller-ha-pacemaker.rst</div><div id="yui_3_16_0_1_1434657432445_658277" dir="ltr"> controller-ha-galera.rst</div><div id="yui_3_16_0_1_1434657432445_658280" dir="ltr"> controller-ha-rabbitmq.rst<br></div><div id="yui_3_16_0_1_1434657432445_658279" dir="ltr"> controller-ha-haproxy.rst</div><div id="yui_3_16_0_1_1434657432445_658323" dir="ltr"> et cetera</div><div id="yui_3_16_0_1_1434657432445_658375" dir="ltr"><br></div><div id="yui_3_16_0_1_1434657432445_658377" dir="ltr">It also makes for a very cluttered source directory. Things would be cleaner if we had</div><div id="yui_3_16_0_1_1434657432445_658423" dir="ltr">only the controller-ha.rst file in the source directory, with a controller subdirectory that</div><div id="yui_3_16_0_1_1434657432445_658465" dir="ltr">had files named pacemaker.rst, galera.rst, rabbitmq.rst, haproxy.rst...</div><div id="yui_3_16_0_1_1434657432445_658675" dir="ltr"><br></div><div id="yui_3_16_0_1_1434657432445_658676" dir="ltr">As appropriate, the subdirectory might have a subdirectory. For example, the galera</div><div id="yui_3_16_0_1_1434657432445_658759" dir="ltr">subtopic might have separate sections for MySQL and MariaDB and maybe another</div><div id="yui_3_16_0_1_1434657432445_658760" dir="ltr">database or two. Different people might work on different database options, so having</div><div id="yui_3_16_0_1_1434657432445_658761" dir="ltr">a galera subdirectory with different files for the different database architectures makes</div><div id="yui_3_16_0_1_1434657432445_658762" dir="ltr">sense.</div><div id="yui_3_16_0_1_1434657432445_658845" dir="ltr"><br></div><div id="yui_3_16_0_1_1434657432445_659331" dir="ltr">On the other hand, the haproxy subtopic might have sections for install, configure, verify,</div><div id="yui_3_16_0_1_1434657432445_659285" dir="ltr">launch. I don't see much advantage in breaking those up into separate files, although I</div><div id="yui_3_16_0_1_1434657432445_659288" dir="ltr">know some people who would advocate for that.<br></div><div id="yui_3_16_0_1_1434657432445_659266" dir="ltr"><br></div><div id="yui_3_16_0_1_1434657432445_659283" dir="ltr">In addition to breaking the files up for parallel development, well-chosen discrete files can</div><div id="yui_3_16_0_1_1434657432445_659281" dir="ltr">simplify restructuring the material -- rather than having to yank 75 lines of doc source from</div><div id="yui_3_16_0_1_1434657432445_659268" dir="ltr">one file and insert it into another, you can just move the inclusion line from one topic file</div><div id="yui_3_16_0_1_1434657432445_659270" dir="ltr">to another and voila!</div><div id="yui_3_16_0_1_1434657432445_659272" dir="ltr"><br></div><div id="yui_3_16_0_1_1434657432445_659274" dir="ltr">What does everyone else think?</div><div id="yui_3_16_0_1_1434657432445_659276" dir="ltr">meg<br></div><div id="yui_3_16_0_1_1434657432445_657956"><span></span></div><br> <blockquote id="yui_3_16_0_1_1434657432445_657937" style="border-left: 2px solid rgb(16, 16, 255); margin-left: 5px; margin-top: 5px; padding-left: 5px;"> <div id="yui_3_16_0_1_1434657432445_657936" style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 16px;"> <div id="yui_3_16_0_1_1434657432445_657935" style="font-family: HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif; font-size: 16px;"> <div id="yui_3_16_0_1_1434657432445_657934" dir="ltr"> <hr size="1"> <font face="Arial" size="2"> <b><span style="font-weight:bold;">From:</span></b> Andreas Jaeger <aj@suse.com><br> <b><span style="font-weight: bold;">To:</span></b> "openstack-docs@lists.openstack.org" <openstack-docs@lists.openstack.org> <br> <b><span style="font-weight: bold;">Sent:</span></b> Friday, June 19, 2015 11:40 AM<br> <b><span style="font-weight: bold;">Subject:</span></b> Re: [OpenStack-docs] RST conversion and file splits ?<br> </font> </div> <div id="yui_3_16_0_1_1434657432445_657939" class="y_msg_container"><br>On 06/19/2015 02:36 PM, Andreas Jaeger wrote:<br clear="none">> With DocBook, we had often included one file from another - and used<br clear="none">> that included file only in a single place. So, there was no reason to do<br clear="none">> it from an editors point of view, just splitting of content.<br clear="none">><br clear="none">> Looking at <a id="yui_3_16_0_1_1434657432445_657938" shape="rect" href="https://review.openstack.org/#/c/192575/" target="_blank">https://review.openstack.org/#/c/192575/ </a>I wonder what's the<br clear="none">> right thing to do. The included file is not mentioned in a table of<br clear="none">> contents and thus we normally use ":orphan:" but this does not work<br clear="none">> here, so a hidden toctable is used.<br clear="none">><br clear="none">> BUT why should we split this up in several files at all? If there's a<br clear="none">> toc table used - or the file is used in several places -, splitting it<br clear="none">> up is fine but just for inclusion I see no need for separate files.<br clear="none">><br clear="none">> Or is there a preference for how large files are and how to split them up?<br clear="none">><br clear="none">> Is there any guidance we want to follow for file splits like these?<br clear="none">><br clear="none">> Looking at the :orphan:/hidden toctable constructs, I'm against file<br clear="none">> splits and therefore ask to see whether we can reach some consensus that<br clear="none">> I then follow in further reviews,<br clear="none"><br clear="none">Another example with the same problem:<br clear="none"><br clear="none"><a shape="rect" href="https://review.openstack.org/#/c/193518/2/doc/admin-guide-cloud-rst/source/blockstorage.rst" target="_blank">https://review.openstack.org/#/c/193518/2/doc/admin-guide-cloud-rst/source/blockstorage.rst</a><div class="qtdSeparateBR"><br><br></div><div class="yqt5680746610" id="yqtfd52034"><br clear="none"><br clear="none">Andreas<br clear="none">-- <br clear="none"> Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi<br clear="none"> SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br clear="none"> GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,<br clear="none"> HRB 21284 (AG Nürnberg)<br clear="none"> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br clear="none"><br clear="none"><br clear="none">_______________________________________________<br clear="none">OpenStack-docs mailing list<br clear="none"><a shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br clear="none"><a shape="rect" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br clear="none"></div><br><br></div> </div> </div> </blockquote> </div></body></html>