Ah, good. The doxygen site's showing the correct version number now.
Another point in favour of integrating source docs into the handbook: I
think the docs for libgnunetutil and other documentation for libraries
could really benefit from it, as they are rather skeletal and the
doxygen site isn't the most intuitively organised thing in the world
(are there ways to improve that?).
I have some ideas for how the GNUnet documentation can be radically
reorganised, to make it more concise, taking after Python's documentation:
* docs.gnunet.org (Everything in one place!)
* Installation and setup
(www/Install, Tutorial install, and Handbook install sections,
configuration sections from handbook and tutorial)
* User's Manual
(Using GNUnet, www/Use)
* Developer's Manual
(rest of Tutorial, GNUnet Developer Handbook, GNUnet Contributor's
Handbook)
* REST API documentation
* Doxygen-generated source docs
* Living Standards Documents
* Bibliography
* History/License of GNUnet (could be split, not quite as entangled as
for Python)
* Contributing to docs
* Glossary
(www/Glossary, allow us to reference it from the docs, and could also
incorporate the Key Concepts section of the handbook)
I've knocked together a mockup with a few currently half-finished
transcriptions from the handbook's .texi files, and a logo I yanked from
the website source. The TeXinfo is a lot more rough around the edges as
I haven't done as much configuration work for it.
I've also gone through the longest of the Handbook chapters by far, the
entire Developer's Handbook, and broken it apart by section. These
smaller .texi files occupy first-draft positions in the dev handbook's
directory tree. I haven't read every section in detail, so a few of
these sections may be in odd places. I have done similar things for the
preface and the
What needs to be done so that I can push this to origin and everyone can
see it? I think the work I've done so far is a bit too much for a patch.
When that does happen, there are a few items of note in the HTML, that
we might find useful:
* Search bar! Haven't tried it yet, but should be useful.
* A to-do list can be generated from reST directives in the source,
have a look at it in the contributing section!
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.
As a more tangential aside: what/who is the REST API for a GNUnet
component for?
I hope this isn't too much to spring on you at once.
- 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
