Open Stack

On Fri, Sep 25, 2015 at 9:24 AM, Christian Berendt <christian at berendt.io>
wrote:

> On 09/25/2015 03:26 AM, Matt Kassawara wrote:
>
>> While updating the installation guide for Liberty, I found a conditional
>> rendering problem. Our conventions state we use the heading "~~~" for
>> sections and "---" for subsections. If I use this order under a
>> conditional, the content disappears from the HTML output. If I flip the
>> order, the content appears in the HTML output. I wrote a handful of test
>> lines in my keystone patch [1] to provide an example of the problem. Any
>> ideas?
>>
>
> According to http://docutils.sourceforge.net/docs/user/rst/quickstart.html
> the correct order is:
>
> Chapter 1 Title
> ===============
>
> Section 1.1 Title
> -----------------
>
> Subsection 1.1.1 Title
> ~~~~~~~~~~~~~~~~~~~~~~
>
> Looks like our conventions are wrong.
>

I've dug into this in the past, and as it turns out, we simply used what
was given to us by pandoc when converting. Sphinx and RST have differing
examples, neither is "correct" rather we just pick a convention and stick
to it. Right now we are consistent with what pandoc gave us in our
migration tooling.

Matt's issue was unrelated as it turns out, there was some extra
indentation confusing the conditionals.

I'd prefer to stick with what we have for now. Only other consideration we
might make would be to look at Python's conventions
https://docs.python.org/devguide/documenting.html#sections.


   - # with overline, for parts
   - * with overline, for chapters
   - =, for sections
   - -, for subsections
   - ^, for subsubsections

Thanks,

Anne


>
> Christian.
>
> --
> Christian Berendt
> Cloud Solution Architect
> Mail: berendt at b1-systems.de
>
> B1 Systems GmbH
> Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de
> GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
Rackspace
Principal Engineer
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150926/12e50622/attachment.html>