[OpenStack-docs] RST conversion and file splits ? (Meg McRoberts)

Meg McRoberts dreidellhasa at yahoo.com
Mon Jun 22 08:25:35 UTC 2015 

The general flaw I see for gerrit review, especially with smaller files, is that 
reviews address the specific text in a section but not the flow of the largersection.  But, of course, larger files don't necessarily guarantee that we getthat sort of review -- people can just read/review a small part of the larger file ;-)
Do we need to use the toctree block for all file inclusions?  I do not completelyunderstand toctree, but there is also the more generic include statement:
  .. include :: /{pathname}/filename
One difference seems to be that, with this construction, you would not startall files with the title block:

   =====   Title   =====
Instead, the first title in a section would be marked for the heading level it shoulduse, so -------------, then ~~~~~~~, then ++++++, et cetera.  

Can the filenames listed in a toctree list specify a file in a sub-directory?  If we areusing smallish source files and locate all those files in the same directory ratherthan using subdirectories, it seems like we are going to have inordinately messysource directories, probably with very long filenames that are awkward...
meg

 


      From: Tom Fifield <tom at openstack.org>
 To: openstack-docs at lists.openstack.org 
 Sent: Sunday, June 21, 2015 11:52 PM
 Subject: Re: [OpenStack-docs] RST conversion and file splits ? (Meg McRoberts)
   
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
> 


_______________________________________________
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/20150622/e3db8e08/attachment-0001.html>

More information about the OpenStack-docs mailing list