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
