Re: Attacking the documentation monster

[Schanzenbach, Martin]

Hi,

> On 27. Jul 2022, at 19:35, Willow Liquorice <willow@howhill.com> wrote:
> 
> 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).
> 

Ah great. I started with a blank slate and used markdown. I wanted to

1. Weed out and reorganize the docs (The "Installation" chapter is just wrong 
in all kinds of ways)
2. Use Sphinx and ideally, markdown

Both requires quite a lot of manual work.
So, I guess we need to decided on what to proceed.
But if you say that the pandoc result is workable that is fine with me. I think 
there are rst to markdown converters for sphinx as well.

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

I am not sure I understand "place". Do you mean you did not know where to sign 
it on the document? (the answer is anywhere)

> 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?
> 

Sounds like something that may go somewhere into contrib (the lua script/nvim 
config).
For now, I would like to tackle the handbook first.

BR
Martin

> 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
>>>>>>>>>>>>>> 
>>>>>>>>>>>>> 
>>>>>>>>>> 
>>>>>>>> 
>>>>>> 
>>>>> 
>>> 
>

signature.asc
Description: Message signed with OpenPGP