gnunet-developers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Attacking the documentation monster


From: Martin Schanzenbach
Subject: Re: Attacking the documentation monster
Date: Wed, 03 Aug 2022 05:48:03 +0000

Hi all,

the new documentation is not live at https://docs.gnunet.org.
Please report any issues here or in the bugtracker.
Thanks Willow for your work in particular.
I think this gives a much better impression of the project.

As a sideeffect, GNUnet now no longer depends on texinfo in order to
build documentation (instead it depends on sphinx).

BR
Martin

Excerpts from Martin Schanzenbach's message of 2022-07-31 10:44:20 +0000:
> Hi all,
> 
> I created a new separate repo here for the new handbook format:
> https://git.gnunet.org/gnunet-handbook.git
> As you can see, I have decided to use markdown instead of rst.
> 
> We can include it as as submodule for gnunet.git when the time comes.
> I have already "translated" some of the chapters from the old handbook,
> but I do not want a 1:1 copy as we should use this chance to improve it.
> You can see the current state here:
> https://docs.gnunet.org/doc-ng
> 
> It is integrated with CI so it should always be up to date.
> We will integrate the work by Willow asap.
> If you want to tackle any parts and improve them, feel free to send us
> patches/diffs.
> As it is now markdown, it should be quite easy to contribute.
> 
> BR
> Martin
> 
> Excerpts from Willow Liquorice's message of 2022-05-24 22:19:38 +0100:
> > 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
> > >>>>>>>>>>>
> > >>>>>>>>>>
> > >>>>>>>
> > >>>>>
> > >>>
> > >>
> > > 

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]