Re: Updates: need doc reviews, Docker changes, beta release of 2.3.0

Hi Ralf:

In message <[email protected]>,
Ralf Schlatterbeck writes:
>On Sun, May 14, 2023 at 04:09:15PM -0400, John P. Rouillard wrote:
>
>> Speaking of enhanced docs, I have done some restructuring, cleanup and
>> re-styling of the docs. There is one more major change to come before
>> release:
>> 
>>    Moving the top of customizing.html to a separate reference.html doc.
>> 
>> Everything on that page before the Examples section will be moved.  I
>> am trying to rework the docs according to the diataxis
>> (https://diataxis.fr/) framework. I can use help with this. If anybody
>> has friends who are into documentation (tech writers for example) who
>> would like to help out I would appreciate it if you mention this to
>> them.
>
>Nice!

Thanks I committed this change early this morning and updated all (I
think) of the references to point to the proper doc.

>As far as I understand this, diataxis is a way to structure
>documentation for better human consumption, not a framework for
>formatting documentation?

Correct. It's a framework for information design/architecture. Not
display style.

>> The goal is to increase use of Roundup by making the docs more
>> readable and scanable.
>[...]
>
>How about moving to Sphinx sooner or later?

It is written using Sphinx. Currently it's conf is sphinx 1.8??
compatible bacause that's the newest version I can get to run in our
environment on sourceforge.

I have some shelved patches to allow me to process it with sphinx 5+,
but that would require building off of sourceforge and copying the
generated files to sourceforge. I am trying to keep the build/release
toolchain available on sourceforge but ....

The layout and stylesheets are custom to try to match the styles on
the rest of roundup assets: wiki, issues etc.

>Of course there are other style sheets than the one featured by
>readthedocs.

Overhauling/replacing the styles for moin-moin, issues/roundup is a
distant goal. I have had a readthedocs config file uncommitted in my
working tree for 6+ months. Making all the assets compatible with the
newest toolchains (pyproject.toml for example) is also a distant goal.

Have a great week and thanks for the feedback.

--
				-- rouilj
John Rouillard
===========================================================================
My employers don't acknowledge my existence much less my opinions.