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-pbonz...@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: PGP signature
