Re: [docs] Possible changes to the project docs

["Robert P. J. Day" <rpjday@crashcourse.ca>]

On Wed, 15 Apr 2020, Trevor Woerner wrote:

> On Wed 2020-04-15 @ 11:19:25 AM, Richard Purdie wrote:
> > Basically, the thought is whether to move from docbook to sphinx.
>
> This sounds like a good idea to me.
>
> Prior to yesterday I had never looked into sphinx before. Skimming some
> information about sphinx, it looks like it's flexible with regards to the
> exact formatting you use for, for example, section headings. If that's true, I
> believe we'll need a "coding standard" in place before proceeding. We wouldn't
> want the BSP Manual to use:
>
> 	section 1
> 	^^^^^^^^^
> 	section 1.1
> 	===========
> 	section 1.1.1
> 	-------------
>
> and the Reference Manual to use:
>
> 	section 1
> 	=========
> 	section 1.1
> 	***********
> 	section 1.1.1
> 	^^^^^^^^^^^^^

  absolutely, and i'll throw out one more "coding standard" that i
initially loathed, but came to appreciate -- keep sentences on the
same physical line.

  i first ran into that standard when contributing to the "pro git"
book, and i hated, hated, hated it as it naturally made long sentences
go on forever off the right side of the terminal window.

  however, i grew to like it because it makes side-by-side comparison
trivial and if you ended up with a sentence like that, it made you
reconsider whether you were doing this correctly.

  anyway, yes to the above.

rday

p.s. i've played briefly with sphinx on my fedora 31/32 system -- has
anyone set up a full processing toolchain that can just be purloined
to get started? even though it looks pretty simple.