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 <wil...@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-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: Message signed with OpenPGP
