Open Stack

On 05/13/2015 03:13 PM, Andreas Jaeger wrote:
> On 05/13/2015 02:50 PM, Anne Gentle wrote:
>>
>>
>> On Wed, May 13, 2015 at 1:24 AM, Andreas Jaeger <aj at suse.com
>> <mailto:aj at suse.com>> wrote:
>>
>>     On 05/12/2015 10:55 PM, Lana Brindley wrote:
>>
>>         I’m fine with this approach. Is the issue happening in other
>>         Guides as well?
>>
>>
>>     This is specific to RST.
>>
>>     Separating the two guides this way allows us some nice cleanup, I
>>     wonder why we didn't do it initially;). It's now easier to maintain,
>>
>>
>> We did it initially to prove we could have conditional inclusions at the
>> file level.
>>
>> Now, what I'm not sure of is: have we proven Sphinx doesn't handle
>> conditional inclusions as we'd expect? That certainly is a consideration
>> for the next RST migrations.
>
> We still can do it - using :only: admin_only or :only:user_only on parts
> of a file. If we want to keep that option, we can leave the tags support
> in and we do not merge this patch:
> https://review.openstack.org/#/c/182444/
>
> The sphinx extension is usefull for *file* level inclusion and with the
> separation, we do not need it anymore,

Btw. we also have other means for exclusion now: Marking a file in 
common as :orphan: or use the exclude_pattern to exclude certain files.

So, my current understanding: the :only: might be interesting - and the 
firstapp document is using it, but the file level scope seems not to be 
needed.

I'm fine leaving both in for now and see whether we need and reconsider 
in a few months - or remove now and put it in again later if needed.

I've marked the single patch as WIP, the others can go in as is,


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