[PATCH 0/1] c-user: Generate I/O Manager documentation

[Sebastian Huber]

On 01/10/2020 06:19, Chris Johns wrote:
> On 30/9/20 6:04 pm, Sebastian Huber wrote:
>> On 29/09/2020 16:59, Sebastian Huber wrote:
>>
>>> This is the first generated documentation of a manager. For the PDF
>>> output please have a look at:
>>>
>>> https://ftp.rtems.org/pub/rtems/people/sebh/c-user.pdf
>>>
>>> Please review the layout.  I changed the layout to use definition lists
>>> instead of tables.  The benefit of definition lists is that the layout
>>> of longer text paragraphs is much nicer compared to tables (at least for
>>> the PDF output).
>>>
>>> Sebastian Huber (1):
>>>     c-user: Generate I/O Manager documentation
>>>
>>>    c-user/io/directives.rst   | 550 ++++++++++++++++++-------------------
>>>    c-user/io/introduction.rst |  37 ++-
>>>    2 files changed, 295 insertions(+), 292 deletions(-)
>>>
>> The vertical spacing of the definition lists was a bit odd.
> 
> Sorry, I commented in my other post then saw this. Please ignore my vertical
> spacing comments there.
> 
>> In the Latex
>> enumitem package documentation there is a note that nested definition lists with
>> the "nextline" style are not supported.
> 
> OK.
> 
>> I changed the formatting to use the .. rubric directive.
> 
> Does this change what we need to install to build a PDF?

No, the rubric directive is a standard Sphinx feature:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-rubric

"This directive creates a paragraph heading that is not used to create a 
table of contents node."

I think this matches quite well with our use case here.

> 
>> Please have a look at this PDF:
>>
>> https://ftp.rtems.org/pub/rtems/people/sebh/c-user-2.pdf
>>
>> Only the IO Manager and Event Manager chapters use the new formatting.
> 
> The vertical spacing is much better but the headings are currently bold and that
> has gone. I am not sure that is a major issue.

If we keep the rubric directive, then I think this should be fixed by a 
style definition if possible.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.