<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="yiv2412491002"><div id="yui_3_16_0_1_1434943482102_72216"><div id="yui_3_16_0_1_1434943482102_72215" style="color:#000;background-color:#fff;font-family:HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif;font-size:16px;"><div>The general flaw I see for gerrit review, especially with smaller files, is that <br clear="none"></div><div dir="ltr">reviews address the specific text in a section but not the flow of the larger</div><div dir="ltr">section. But, of course, larger files don't necessarily guarantee that we get</div><div dir="ltr">that sort of review -- people can just read/review a small part of the larger file ;-)</div><div dir="ltr"><br clear="none"></div><div dir="ltr" id="yiv2412491002yui_3_16_0_1_1434943482102_69010">Do we need to use the toctree block for all file inclusions? I do not completely</div><div dir="ltr" id="yiv2412491002yui_3_16_0_1_1434943482102_69553">understand toctree, but there is also the more generic include statement:</div><div dir="ltr"><br clear="none"></div><div dir="ltr"> .. include :: /{pathname}/filename</div><div id="yui_3_16_0_1_1434943482102_72219" dir="ltr"><br clear="none"></div><div id="yui_3_16_0_1_1434943482102_72218" dir="ltr">One difference seems to be that, with this construction, you would not start</div><div id="yui_3_16_0_1_1434943482102_72217" dir="ltr">all files with the title block:<br></div><div id="yui_3_16_0_1_1434943482102_72222" dir="ltr"><br clear="none"></div><div id="yui_3_16_0_1_1434943482102_72214" dir="ltr"> =====</div><div id="yui_3_16_0_1_1434943482102_72223" dir="ltr"> Title</div><div id="yui_3_16_0_1_1434943482102_72224" dir="ltr"><div id="yui_3_16_0_1_1434943482102_73669"> =====</div><div><br></div><div id="yui_3_16_0_1_1434943482102_74498">Instead, the first title in a section would be marked for the heading level it should</div><div>use, so -------------, then ~~~~~~~, then ++++++, et cetera. <br></div><div id="yui_3_16_0_1_1434943482102_74042"><br></div><div id="yui_3_16_0_1_1434943482102_74043">Can the filenames listed in a toctree list specify a file in a sub-directory? If we are</div><div dir="ltr">using smallish source files and locate all those files in the same directory rather</div><div id="yui_3_16_0_1_1434943482102_74499" dir="ltr">than using subdirectories, it seems like we are going to have inordinately messy</div><div dir="ltr">source directories, probably with very long filenames that are awkward...</div><div id="yui_3_16_0_1_1434943482102_74501" dir="ltr"><br></div><div id="yui_3_16_0_1_1434943482102_74500" dir="ltr">meg<br></div></div><div id="yiv2412491002yui_3_16_0_1_1434943482102_66840"><span></span></div><br clear="none"> <div class="qtdSeparateBR"><br><br></div><div class="yiv2412491002yqt7496432783" id="yiv2412491002yqt51410"><blockquote id="yiv2412491002yui_3_16_0_1_1434943482102_66832" style="border-left:2px solid rgb(16, 16, 255);margin-left:5px;margin-top:5px;padding-left:5px;"> <div id="yiv2412491002yui_3_16_0_1_1434943482102_66831" style="font-family:HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif;font-size:16px;"> <div id="yiv2412491002yui_3_16_0_1_1434943482102_66830" style="font-family:HelveticaNeue, Helvetica Neue, Helvetica, Arial, Lucida Grande, sans-serif;font-size:16px;"> <div dir="ltr" id="yiv2412491002yui_3_16_0_1_1434943482102_66829"> <hr id="yiv2412491002yui_3_16_0_1_1434943482102_66833" size="1"> <font id="yiv2412491002yui_3_16_0_1_1434943482102_66828" face="Arial" size="2"> <b id="yiv2412491002yui_3_16_0_1_1434943482102_69282"><span id="yiv2412491002yui_3_16_0_1_1434943482102_69281" style="font-weight:bold;">From:</span></b> Tom Fifield <tom@openstack.org><br clear="none"> <b><span style="font-weight:bold;">To:</span></b> openstack-docs@lists.openstack.org <br clear="none"> <b><span style="font-weight:bold;">Sent:</span></b> Sunday, June 21, 2015 11:52 PM<br clear="none"> <b><span style="font-weight:bold;">Subject:</span></b> Re: [OpenStack-docs] RST conversion and file splits ? (Meg McRoberts)<br clear="none"> </font> </div> <div class="yiv2412491002y_msg_container" id="yiv2412491002yui_3_16_0_1_1434943482102_69011"><br clear="none">On 21/06/15 02:58, Olena Logvinova wrote:<br clear="none">> Good Saturday to everyone!<br clear="none">> <br clear="none">> Thanks Andreas for opening this topic. And thanks much Meg for such a<br clear="none">> detailed answer!<br clear="none">> <br clear="none">> I agree with Meg here + another argument to have small children files<br clear="none">> that are logical sub-sections of 1 chapter: it's much easier to review<br clear="none">> and merge these in comparison with 200-300 lines' looong memoirs. I<br clear="none">> prefer files no longer than 100-150 lines. But I will gladly hear out<br clear="none">> other ideas on this matter. <br clear="none"><br clear="none">Generally agree with Lena and Meg here - I also prefer child file<br clear="none">inclusions, with files of a size that makes sense for how they are used.<br clear="none"><br clear="none">I found this in the sphinx docs, which might let us use simple include<br clear="none">statements without worrying about the hidden toctree every time:<br clear="none"><br clear="none">"""<br clear="none">In cases where you want to have only one top-level toctree and hide all<br clear="none">other lower level toctrees you can add the “includehidden” option to the<br clear="none">top-level toctree entry:<br clear="none"><br clear="none">.. toctree::<br clear="none"> :includehidden:<br clear="none">"""<br clear="none"><br clear="none">I guess that can also be overridden by explicitly making another toctree<br clear="none">in a child file if we did want one.<br clear="none"><br clear="none">Does that work?<br clear="none"><br clear="none"><br clear="none">> Best<br clear="none">> Lena<br clear="none">> <br clear="none">> On Sat, Jun 20, 2015 at 3:00 PM,<br clear="none">> <<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs-request@lists.openstack.org" target="_blank" href="mailto:openstack-docs-request@lists.openstack.org">openstack-docs-request@lists.openstack.org</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs-request@lists.openstack.org" target="_blank" href="mailto:openstack-docs-request@lists.openstack.org">openstack-docs-request@lists.openstack.org</a>>> wrote:<br clear="none">> <br clear="none">> Send OpenStack-docs mailing list submissions to<br clear="none">> <a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" target="_blank" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" target="_blank" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>><br clear="none">> <br clear="none">> To subscribe or unsubscribe via the World Wide Web, visit<br clear="none">> <br clear="none">> <a rel="nofollow" shape="rect" target="_blank" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br clear="none">> or, via email, send a message with subject or body 'help' to<br clear="none">> <a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs-request@lists.openstack.org" target="_blank" href="mailto:openstack-docs-request@lists.openstack.org">openstack-docs-request@lists.openstack.org</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs-request@lists.openstack.org" target="_blank" href="mailto:openstack-docs-request@lists.openstack.org">openstack-docs-request@lists.openstack.org</a>><br clear="none">> <br clear="none">> You can reach the person managing the list at<br clear="none">> <a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs-owner@lists.openstack.org" target="_blank" href="mailto:openstack-docs-owner@lists.openstack.org">openstack-docs-owner@lists.openstack.org</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs-owner@lists.openstack.org" target="_blank" href="mailto:openstack-docs-owner@lists.openstack.org">openstack-docs-owner@lists.openstack.org</a>><br clear="none">> <br clear="none">> When replying, please edit your Subject line so it is more specific<br clear="none">> than "Re: Contents of OpenStack-docs digest..."<br clear="none">> <br clear="none">> <br clear="none">> Today's Topics:<br clear="none">> <br clear="none">> 1. Re: RST conversion and file splits ? (Meg McRoberts)<br clear="none">> <br clear="none">> <br clear="none">> ----------------------------------------------------------------------<br clear="none">> <br clear="none">> Message: 1<br clear="none">> Date: Fri, 19 Jun 2015 20:59:19 +0000 (UTC)<br clear="none">> From: Meg McRoberts <<a rel="nofollow" shape="rect" ymailto="mailto:dreidellhasa@yahoo.com" target="_blank" href="mailto:dreidellhasa@yahoo.com">dreidellhasa@yahoo.com</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:dreidellhasa@yahoo.com" target="_blank" href="mailto:dreidellhasa@yahoo.com">dreidellhasa@yahoo.com</a>>><br clear="none">> To: Andreas Jaeger <<a rel="nofollow" shape="rect" ymailto="mailto:aj@suse.com" target="_blank" href="mailto:aj@suse.com">aj@suse.com</a> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:aj@suse.com" target="_blank" href="mailto:aj@suse.com">aj@suse.com</a>>>,<br clear="none">> "<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" target="_blank" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" target="_blank" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>>"<br clear="none">> <<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" target="_blank" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" target="_blank" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>>><br clear="none">> Subject: Re: [OpenStack-docs] RST conversion and file splits ?<br clear="none">> Message-ID:<br clear="none">> <br clear="none">> <<a rel="nofollow" shape="rect" ymailto="mailto:1002285246.2547175.1434747559361.JavaMail.yahoo@mail.yahoo.com" target="_blank" href="mailto:1002285246.2547175.1434747559361.JavaMail.yahoo@mail.yahoo.com">1002285246.2547175.1434747559361.JavaMail.yahoo@mail.yahoo.com</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:1002285246.2547175.1434747559361.JavaMail.yahoo@mail.yahoo.com" target="_blank" href="mailto:1002285246.2547175.1434747559361.JavaMail.yahoo@mail.yahoo.com">1002285246.2547175.1434747559361.JavaMail.yahoo@mail.yahoo.com</a>>><br clear="none">> Content-Type: text/plain; charset="utf-8"<br clear="none">> <br clear="none">> I do not thoroughly grok the intricacies of toctree --I just try to<br clear="none">> follow whatsomeone else does and hope it doesn't blow up on me ;-)<br clear="none">> However, it sounds like you are musing about issues of source file<br clear="none">> structureand I have been thinking about that a bit.? It sounds like<br clear="none">> you are thinking abouthaving one big file per "topic".? I have<br clear="none">> worked with people who argue that nodoc source file should have more<br clear="none">> than one heading in it -- each subsectiongets its own file.? My own<br clear="none">> preferences fall somewhere in the middle, but findingthe "sweet<br clear="none">> spot" between the two is non-trivial.<br clear="none">> The great advantage of having smaller files is that different people<br clear="none">> can work ondifferent sections at the same time without causing<br clear="none">> horrific 6-way-merge scenarios.For example, in the new HA Guide, we<br clear="none">> have a topic about configuring the controllernode for high<br clear="none">> availability.? This has subtopics for pacemaker/corosync,<br clear="none">> mysql/galera, rabbitmq,<br clear="none">> HAProxy, keystone, et cetera.? The writers and reviewers for each of<br clear="none">> these subsectionsare often different people, so having those<br clear="none">> subtopics in different files that are includedin the larger topic<br clear="none">> file has definite advantages.<br clear="none">> I would advocate a less-flat directory structure for the source<br clear="none">> files.? Our current practiceseems to be to give a common "front-end"<br clear="none">> to all the subfiles for a topic, which causessome really long file<br clear="none">> names; for example:<br clear="none">> ???? controller-ha.rst???? controller-ha-pacemaker.rst????<br clear="none">> controller-ha-galera.rst???? controller-ha-rabbitmq.rst<br clear="none">> ???? controller-ha-haproxy.rst???? et cetera<br clear="none">> It also makes for a very cluttered source directory.? Things would<br clear="none">> be cleaner if we hadonly the controller-ha.rst file in the source<br clear="none">> directory, with a controller subdirectory thathad files named<br clear="none">> pacemaker.rst, galera.rst, rabbitmq.rst, haproxy.rst...<br clear="none">> As appropriate, the subdirectory might have a subdirectory.? For<br clear="none">> example, the galerasubtopic might have separate sections for MySQL<br clear="none">> and MariaDB and maybe anotherdatabase or two.? Different people<br clear="none">> might work on different database options, so havinga galera<br clear="none">> subdirectory with different files for the different database<br clear="none">> architectures makessense.<br clear="none">> On the other hand, the haproxy subtopic might have sections for<br clear="none">> install, configure, verify,launch.? I don't see much advantage in<br clear="none">> breaking those up into separate files, although Iknow some people<br clear="none">> who would advocate for that.<br clear="none">> <br clear="none">> In addition to breaking the files up for parallel development,<br clear="none">> well-chosen discrete files cansimplify restructuring the material --<br clear="none">> rather than having to yank 75 lines of doc source fromone file and<br clear="none">> insert it into another, you can just move the inclusion line from<br clear="none">> one topic fileto another and voila!<br clear="none">> What does everyone else think?meg<br clear="none">> <br clear="none">> <br clear="none">> From: Andreas Jaeger <<a rel="nofollow" shape="rect" ymailto="mailto:aj@suse.com" target="_blank" href="mailto:aj@suse.com">aj@suse.com</a> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:aj@suse.com" target="_blank" href="mailto:aj@suse.com">aj@suse.com</a>>><br clear="none">> To: "<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" target="_blank" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" target="_blank" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>>"<br clear="none">> <<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" target="_blank" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:openstack-docs@lists.openstack.org" target="_blank" href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>>><br clear="none">> Sent: Friday, June 19, 2015 11:40 AM<br clear="none">> Subject: Re: [OpenStack-docs] RST conversion and file splits ?<br clear="none">> <br clear="none">> 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<br clear="none">> 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 rel="nofollow" shape="rect" target="_blank" href="https://review.openstack.org/#/c/192575/">https://review.openstack.org/#/c/192575/ </a>I wonder<br clear="none">> 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<br clear="none">> 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<br clear="none">> 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 rel="nofollow" shape="rect" target="_blank" href="https://review.openstack.org/#/c/193518/2/doc/admin-guide-cloud-rst/source/blockstorage.rst">https://review.openstack.org/#/c/193518/2/doc/admin-guide-cloud-rst/source/blockstorage.rst</a><br clear="none">> <br clear="none">> <br clear="none">> <br clear="none">> Andreas<br clear="none">> --<br clear="none">> ? Andreas Jaeger aj@{suse.com <<a rel="nofollow" shape="rect" target="_blank" href="http://suse.com/">http://suse.com</a>>,opensuse.org<br clear="none">> <<a rel="nofollow" shape="rect" target="_blank" href="http://opensuse.org/">http://opensuse.org</a>>} 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 rel="nofollow" shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" target="_blank" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" target="_blank" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a>><br clear="none">> <a rel="nofollow" shape="rect" target="_blank" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br clear="none">> <br clear="none">> <br clear="none">> <br clear="none">> -------------- next part --------------<br clear="none">> An HTML attachment was scrubbed...<br clear="none">> URL:<br clear="none">> <<a rel="nofollow" shape="rect" target="_blank" href="http://lists.openstack.org/pipermail/openstack-docs/attachments/20150619/10e0cb74/attachment-0001.html">http://lists.openstack.org/pipermail/openstack-docs/attachments/20150619/10e0cb74/attachment-0001.html</a>><br clear="none">> <br clear="none">> ------------------------------<br clear="none">> <br clear="none">> _______________________________________________<br clear="none">> OpenStack-docs mailing list<br clear="none">> <a rel="nofollow" shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" target="_blank" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br clear="none">> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" target="_blank" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a>><br clear="none">> <a rel="nofollow" shape="rect" target="_blank" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br clear="none">> <br clear="none">> <br clear="none">> End of OpenStack-docs Digest, Vol 36, Issue 48<br clear="none">> **********************************************<br clear="none">> <br clear="none">> <br clear="none">> <br clear="none">> <br clear="none">> -- <br clear="none">> Best regards,<br clear="none">> Olena Logvinova,<br clear="none">> Technical Writer | Mirantis, Kharkiv | 38, Lenin av., Kharkiv<br clear="none">> <a rel="nofollow" shape="rect" ymailto="mailto:ologvinova@mirantis.com" target="_blank" href="mailto:ologvinova@mirantis.com">ologvinova@mirantis.com</a> <mailto:<a rel="nofollow" shape="rect" ymailto="mailto:ologvinova@mirantis.com" target="_blank" href="mailto:ologvinova@mirantis.com">ologvinova@mirantis.com</a>> | +380950903196<br clear="none">> <tel:%2B380950903196><div class="yiv2412491002qtdSeparateBR"><br clear="none"><br clear="none"></div><div class="yiv2412491002yqt0784308351" id="yiv2412491002yqtfd96769"><br clear="none">> <br clear="none">> <br clear="none">> _______________________________________________<br clear="none">> OpenStack-docs mailing list<br clear="none">> <a rel="nofollow" shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" target="_blank" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br clear="none">> <a rel="nofollow" shape="rect" target="_blank" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br clear="none">> <br clear="none"><br clear="none"><br clear="none">_______________________________________________<br clear="none">OpenStack-docs mailing list<br clear="none"><a rel="nofollow" shape="rect" ymailto="mailto:OpenStack-docs@lists.openstack.org" target="_blank" href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br clear="none"><a rel="nofollow" shape="rect" target="_blank" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a></div><br clear="none"><br clear="none"></div> </div> </div> </blockquote></div> </div></div></div></div></body></html>