[Cuis-dev] Wiki Niceness (WAS: Re: [IMPROV] Add convenience method to read JSON strings)

[Nicola Mingotti]

Hi Gerald,

the output of Sphinx is very nice to see. I will consider this option.

For the moment I will keep on adding notes in GitHub because it is least 
effort option.

bye
Nicola



On 8/12/21 7:52 PM, Gerald Klix via Cuis-dev wrote:
> When writing documentation I always come back to Sphinx.
> I tried various static site generators and one CMS (Plone)
> I tried Erudite and added HTML export, but I was not pleased
> with the result.
>
> I am convinced it is worth the effort.
> Please look at these Sphinx documents:
>
> http://gf3.klix.ch/overview.html#simple-example
> http://haver.klix.ch/semantics.html
> http://haver.klix.ch/pdf/HaverOnCuis.pdf
> http://gf3.klix.ch/gf3.pdf
> https://docs.python.org/3/tutorial/introduction.html
> https://www.kernel.org/doc/html/latest/
> https://llvm.org/docs/
> https://pygments.org/
>
> and of course:
>
> https://www.sphinx-doc.org/en/master/
>
>
> Sphinx can also create EPUB and some sort of XML output,
> which could be used to create instances of class
> Text in Cuis, which can be used as onboard documentation
> (Look Ma, no internet needed ;~)
> Of course this is a lot of work.
>
> I suggest to keep the wiki and use Sphinx and ReadTheDocs,
> the later can generate documentation for git repos.
> So my suggest is to convert approved parts to
> restructured text and include it in a sphinx document.
> One then can use ReadTheDocs to contentiously create
> the official documentation.
>
> Come to think about it, I can do this even now,
> by creating a new sphinx project
> and copying finished/useful/approved parts of
> the wiki to that document.
>
>
> Best Regards,
>
> Gerald
>
>
> On 8/12/21 6:54 PM, Nicola Mingotti via Cuis-dev wrote:
>>
>> I am lucky to have a guide ! Thank you !
>>
>> Sure I am going to add it to the wiki. But we should find a way to 
>> make the Wiki prettier.
>> Now it is not pretty at all.
>>
>> Look how it looks like in my GoogleDocuments ... just adding a few 
>> colors and faces
>> make it a lot better: https://pasteboard.co/KfzoDct.png
> Ah, sorry, it does not look that much better.
>>
>> bye
>> Nicola
>>
> --- snip ---
>>
>>
>> On 8/12/21 5:25 PM, Gerald Klix wrote:
>>> Perfect! You have mastered this stuff.
>>> Your chain of reasoning should go into the wiki.
>>>>>> Gerald
>>>>
>>