Re: Attacking the documentation monster

[Willow Liquorice]

Hello,

Yeah, I've done quite a bit of work on that front. I believe I used the 
pandoc method in the end to translate it all to (rough) reST. The 
conversion isn't perfect: the heading hierarchy is a bit iffy and it 
completely breaks the index (a blessing and a curse, Sphinx's indexing 
is a lot more sophisticated so rewriting the index would be desirable 
anyway).

I wasn't able to submit any of this because I couldn't find a place to 
sign on the Copyright Assignment.

The Doxygen tidy-up I was doing has stalled out too, because I couldn't 
get the neovim macros I wrote for the task to work reliably. They use 
neovim's LSP integration to find a symbol in the headers, but they rely 
on cursor placement to do that, and the cursor sometimes misses the 
symbol. When they work, everything progresses rather quickly because you 
don't have to wade through the source code.

I'm not sure how easy it would be to share those macros, if anyone wants 
to help me debug them, but I can at least share the Lua functions and 
LSP configuration they use to perform the navigation. Would anyone like 
to see them?

Best wishes,
        Willow Liquorice

On 27/07/2022 18:01, Schanzenbach, Martin wrote:
> 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