Re: Attacking the documentation monster

[Schanzenbach, Martin]

Hi,

I was wondering if you had started with sphinx/rtd for the handbook already?
If not, I have played around with it today and already have migrated some text 
and could commit it to gnunet.git or a new repo.
That would allow anyone to play around and add content.
But if you are already further, I would stop and not do that :)

BR
Martin

> On 24. May 2022, at 23:19, Willow Liquorice <willow@howhill.com> wrote:
> 
> Ah, you can do it through pandoc. I'll bear that in mind and see about 
> adapting it to our repository.
> 
> On 24/05/2022 22:16, Nikita Ronja Gillmann wrote:
>> Hi,
>> qemu did this a while back it seems
>> On 5/24/22 22:38, Willow Liquorice wrote:
>>> As an aside, *does anyone know of any tools to convert TeXinfo to reST*? 
>>> This migration is going to be much smoother if there are.
>> https://patchwork.kernel.org/project/qemu-devel/patch/20200226113034.6741-19-pbonzini@redhat.com/
>>> - Willow
>>> 
>>> On 24/05/2022 18:01, Christian Grothoff wrote:
>>>> The doxygen configuration file in Git just had an ancient version number. 
>>>> I've fixed that now. The rest was up-to-date ;-).
>>>> 
>>>> -Christian
>>>> 
>>>> On 5/23/22 16:24, Willow Liquorice wrote:
>>>>> Just look at https://docs.gnunet.org/doxygen/html/index.html and you'll
>>>>> see what I mean.
>>>>> 
>>>>> - Willow
>>>>> 
>>>>> On 23/05/2022 15:23, Christian Grothoff wrote:
>>>>>> I cannot even find a version number on https://docs.gnunet.org/, so 
>>>>>> that's likely not what you are refering to. So where exactly are you 
>>>>>> looking to find documentation for 0.11.x? Likely some code to update 
>>>>>> some location is not working (or was never written, and someone put 
>>>>>> something out manually...).
>>>>>> 
>>>>>> -Christian
>>>>>> 
>>>>>> On 5/23/22 16:16, Willow Liquorice wrote:
>>>>>>> Alright, doc/sphinx it is.
>>>>>>> 
>>>>>>> The handbook is already intended for two wildly different audiences, 
>>>>>>> what with being both a user's and developer's manual. Having the source 
>>>>>>> code documentation in one place (and possibly better organised) might 
>>>>>>> make it easier to work with, and help keep the Developer's Manual 
>>>>>>> up-to-date.
>>>>>>> 
>>>>>>> On another note, are the online source docs even up to date? The 
>>>>>>> indicated version on them is 0.11.x, which is several years gone at 
>>>>>>> this point.
>>>>>>> 
>>>>>>> Best wishes,
>>>>>>>      Willow
>>>>>>> 
>>>>>>> On 23/05/2022 08:39, Christian Grothoff wrote:
>>>>>>>> On 5/23/22 00:57, Willow Liquorice wrote:
>>>>>>>>> Hello again,
>>>>>>>>> 
>>>>>>>>> Thanks for the info, good to hear that I've got most of it. Setting 
>>>>>>>>> up a branch in my local GNUnet repository, to start experimenting 
>>>>>>>>> with Sphinx, as I write this. Seeing as there's some experience with 
>>>>>>>>> the software in the project already, where would be the most sensible 
>>>>>>>>> place to put the root directory? My thinking is either the repository 
>>>>>>>>> root or the doc folder.
>>>>>>>> 
>>>>>>>> Definitively doc/, I think doc/sphinx/ would be good.
>>>>>>>> 
>>>>>>>>> Would it be sensible to migrate to Sphinx throughout the whole GNUnet 
>>>>>>>>> repository? Breathe (https://www.breathe-doc.org/) could very well 
>>>>>>>>> make the transition easy, as I think it would allow us to read the 
>>>>>>>>> Doxygen comments that are already present in the source code.
>>>>>>>> 
>>>>>>>> I'm not sure importing the Doxygen makes sense, that's very different 
>>>>>>>> from the main handbook/tutorial/man-pages both in terms of style and 
>>>>>>>> audience.
>>>>>>>> 
>>>>>>>> my 2 cents
>>>>>>>> 
>>>>>>>> Christian
>>>>>>>> 
>>>>>>>>> Best wishes,
>>>>>>>>> 
>>>>>>>>>      Willow Liquorice
>>>>>>>>> 
>>>>>>>>> On 22/05/2022 22:27, Christian Grothoff wrote:
>>>>>>>>>> Hi Willow,
>>>>>>>>>> 
>>>>>>>>>> We've been using RST/Sphinx for the GNU Taler documentation, and it 
>>>>>>>>>> can generate reasonable TeXinfo. From that experience, I'm not 
>>>>>>>>>> against converting the existing documentation to RST.
>>>>>>>>>> 
>>>>>>>>>> As far as finding the documentation, I think you found most of it, 
>>>>>>>>>> except maybe the RFC-style specs at https://lsd.gnunet.org/.
>>>>>>>>>> 
>>>>>>>>>> The handbook is supposed to cover things in depth, with different 
>>>>>>>>>> chapters for installation (for the various platforms), users (by 
>>>>>>>>>> application, explaining what each application can do and how to use 
>>>>>>>>>> it) and developers (by subsystem, explaining how each subsystem is 
>>>>>>>>>> supposed to work). The man-pages are supposed to be for the 
>>>>>>>>>> day-to-day usage when someone wants to quickly look up command-line 
>>>>>>>>>> options. The doxygen is for function-level documentation for 
>>>>>>>>>> developers-only.  The tutorial is for newbie-developers, and is a 
>>>>>>>>>> bit dated. Finally, the LSDs are in-depth protocol descriptions for 
>>>>>>>>>> those wanting to do interoperable (re)implementations.
>>>>>>>>>> 
>>>>>>>>>> I hope that answers your questions and look forward to you improving 
>>>>>>>>>> the documentation!
>>>>>>>>>> 
>>>>>>>>>> Happy hacking!
>>>>>>>>>> 
>>>>>>>>>> Christian
>>>>>>>>>> 
>>>>>>>>>> On 5/20/22 02:21, Willow Liquorice wrote:
>>>>>>>>>>> I've got some free time on my hands now, and I gave some thought to 
>>>>>>>>>>> improving the readability of the HTML documentation on the website 
>>>>>>>>>>> (which is what the average prospective GNUnet dev is going to look 
>>>>>>>>>>> at). Read the Docs and friends set the standard in this regard. 
>>>>>>>>>>> Having the contents in a sidebar for easy access (regardless of 
>>>>>>>>>>> your location) would be far more convenient than what's currently 
>>>>>>>>>>> available.
>>>>>>>>>>> 
>>>>>>>>>>> I understand that TeXinfo's HTML generation is a bit simplistic in 
>>>>>>>>>>> the name of compatibility, which, while not a bad thing, results in 
>>>>>>>>>>> a subpar reading experience for the average dev who will, in all 
>>>>>>>>>>> likelihood, be reading the docs on a very capable modern browser.
>>>>>>>>>>> 
>>>>>>>>>>> While thinking about how to improve things with TeXinfo, it 
>>>>>>>>>>> occurred to me that, instead of trying to emulate the experience of 
>>>>>>>>>>> using Read the Docs, one could just use Read the Docs! It's Free 
>>>>>>>>>>> Software, after all. I haven't looked into it too deeply, but if 
>>>>>>>>>>> the .texi sources are converted to the reStructuredText that it 
>>>>>>>>>>> accepts, a migration (or use of a similar platform) might be worth 
>>>>>>>>>>> considering. What do the people here think?
>>>>>>>>>>> 
>>>>>>>>>>> If I'm going to dedicate time to restructuring GNUnet's docs, I 
>>>>>>>>>>> need to know where it all is. I've found four strands of docs in 
>>>>>>>>>>> the repository (Handbook, Tutorial, Doxygen, and man pages), could 
>>>>>>>>>>> someone give me a run-down of the state they're in, how they relate 
>>>>>>>>>>> to one another, and what they're supposed to be for? Is that 
>>>>>>>>>>> everything?
>>>>>>>>>>> 
>>>>>>>>>>> Thanks,
>>>>>>>>>>>      Willow
>>>>>>>>>>> 
>>>>>>>>>>> On 01/03/2022 22:52, Christian Grothoff wrote:
>>>>>>>>>>>> Spam killed this. We already constantly have to delete 'bug 
>>>>>>>>>>>> reports'
>>>>>>>>>>>> from the Web that were submitted as link spam. A wiki will drain
>>>>>>>>>>>> resources to keep the spammers out, and at the same time 
>>>>>>>>>>>> experience says
>>>>>>>>>>>> the contributions will be low quality (it has been tried).
>>>>>>>>>>>> 
>>>>>>>>>>>> If someone really is capable and invests time into contributing to
>>>>>>>>>>>> documentation, they can pick up Git and send patches.
>>>>>>>>>>>> 
>>>>>>>>>>>> On 3/1/22 11:12 PM, madmurphy wrote:
>>>>>>>>>>>>> I don't know if this will be a popular proposal, but I really 
>>>>>>>>>>>>> believe
>>>>>>>>>>>>> that setting up a self-hosted Wiki could be a very good choice. No
>>>>>>>>>>>>> complicate git clone, no complaints, just read/edit what you 
>>>>>>>>>>>>> need, and
>>>>>>>>>>>>> distributed responsibilities about its design and direction.
>>>>>>>>>>>>> 
>>>>>>>>>>>>> My two cents
>>>>>>>>>>>> 
>>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>> 
>>> 
>

signature.asc
Description: Message signed with OpenPGP