View Issue Details

IDProjectCategoryView StatusLast Update
0005121GNUnetwebpagepublic2019-02-28 11:17
Reporterng0Assigned ToChristian Grothoff 
PrioritynormalSeverityminorReproducibilityhave not tried
Status closedResolutionfixed 
Product VersionSVN HEAD 
Target Version0.11.0Fixed in Version0.11.0 
Summary0005121: gnunet.org: create docs.gnunet.org where the documentation is available, and further actions
Description> A git hook or a cron job could then move the result of this to
> for example docs.gnunet.org, which could be set up even before we
> have the new website.

1. We need a "make doc" so that we don't rely on build gnunet for just building the documentation.
2. It should be available at docs.gnunet.org/gnunet/ to ensure that we could potentially have other documentation or text documents at docs.gnunet.org/$name/.
3. A git hook or a cron job could automate this, but the documentation has to build, so we need a check before it is deployed.
Tagsdocumentation

Relationships

child of 0005140 closedChristian Grothoff creation of next gnunet.org (meta-issue) 

Activities

ng0

2017-08-24 10:51

developer   ~0012389

After an initial plain texinfo output, we should consider using sphinx for this job in the future if we get translated documentation.
But this is out of the scope of this bug and should be in a new one.

ng0

2017-08-24 12:54

developer   ~0012390

Last edited: 2017-08-24 12:55

View 2 revisions

> 1. We need a "make doc" so that we don't rely on build gnunet for just building the documentation.

This is resolved and a gnunet-doc package added in the last commits shows how this could be run. However, it still depends on the full dependency checks, so we should introduce something to bypass them.

ng0

2017-08-24 13:17

developer   ~0012391

How much of the basic dependencies are available on the web server? If it just runs like this we could continue to step 2 and 3.

Christian Grothoff

2017-10-04 15:21

manager   ~0012459

Are all the dependencies we need in Guix? I would really prefer to have a clean, fully automated and fully cloneable system definition based on Guix for gnunet.org in the future. If that's unrealistic, I can trivially install whatever Debian packages are missing on gnunet.org.

ng0

2017-10-28 23:47

developer   ~0012524

As a note on documentation, not the OS-specific task I work on:
- Change on the recent branch I work on:

I now make use of the same utilities GNU uses to create the Manual/Documentation Pages for hosted projects.
So the documentation builds with the tools present in Guix (and should be portable to other systems even without Guix).
This way to build the Documentation still needs some styling, etc.

ng0

2017-11-04 16:35

developer   ~0012549

I presented two options to the Tor developer community with regards to work on this.
As you can read in this thread, they are open to improving anonbib and sharing efforts to maintain it.
As I believe in fixing problems in cross-community, cross-projects efforts holds more value and reduces the duplicity, this is the way to go. It's still an early idea, but we would basically improve anonbib (many dead links in there), add our own content (GNUnet related papers) and host it in addition to the anonbib site, so that we have two locations. (a rough and short idea)
What do you think?
https://lists.torproject.org/pipermail/tor-dev/2017-November/012545.html

ng0

2017-11-04 16:37

developer   ~0012550

Last edited: 2017-11-04 16:39

View 2 revisions

Additional note:

-> docs.gnunet.org/manual/$NAME

where $NAME is the software, holds the documentation.

-> docs.gnunet.org/anonbib/

would hold the anonbib.

Generation of anonbib is easy, with some pre-recorded hashes it could be done with Guix. I've build it in Guix and updated the cache with the build software outside of the build system. It's possible to do this from within the build system.

Christian Grothoff

2017-11-04 17:09

manager   ~0012551

Working together on the anonbib code: great. Just to clarify: we would host _our_ bibligraphy and they'd continue to host theirs, right? Because the focus (secure P2P vs. anonymity) is somewhat different, so it does make sense to have two different sites with different papers.

ng0

2017-11-04 17:21

developer   ~0012552

> we would host _our_ bibligraphy and they'd continue to host theirs, right?

Yes, although my initial idea was that ours would just be anonbib.cfg extended by our material.
We already have a large mixture in our bibliography mess right now as far as I can tell.

With the system as it is in anonbib.git, anything is possible. But as grarpamp wrote, the code is old the layout needs improvements and patches are welcome.

ng0

2017-11-04 20:59

developer   ~0012562

Some pastes of interest from the ongoing thread.

Roger Dingledine writes:

See also the censorbib, for another example.

Moritz Bartl writes:

There's also a mixnet bibliography at https://bib.mixnetworks.org/ /
https://github.com/applied-mixnetworks/mixbib . If you come across
papers related to mixnets, please submit a patch! Also, we should add
highlights like the anonbib has.

ng0

2017-11-04 21:21

developer   ~0012563

Censorbib: https://censorbib.nymity.ch/

ng0

2018-01-07 20:22

developer   ~0012737

To get back on topic, as I wrote in an email earlier this week:

We'll need https://docs.gnunet.org:
* certificates (easy, LE certs expanding to this subdomain, cronjob daily to check for renewal)
* a location to deploy the gnunetbib (I've started fixing it up), I propose /bib/
* a location to deploy the documentation, I suggest /manual/

Both of these locations should be updated via automated procedures, git hooks or cronjobs.

Christian Grothoff

2018-06-28 10:36

manager   ~0013100

docs.gnunet.org is online. bib.gnunet.org can be quickly put online once we have the generator ready somewhere.

ng0

2018-06-28 11:55

developer   ~0013103

looking good so far.
I expect that there will be a landing page on docs.gnunet.org eventually and subfolder style for documents (TYPE/PROJECT/*).
This way we don't need bib.gnunet.org and can make the bibliography available in docs.gnunet.org/bibliography/

Christian Grothoff

2019-01-26 06:02

manager   ~0013467

Before closing this issue for now, I have two wishes:
1) that the update of docs.gnunet.org is integrated with the Buildbot/CI (with a failure generated to developer if docs do not build due to syntax errors)
2) maybe we could apply some styling? GNU Guix has IIRC some nice CSS for their Texinfo docs Web site (which we could likely copy).

ng0

2019-01-27 15:22

developer   ~0013479

For 1:

As I wrote in my email about mdoc, we wouldn't have the building error if texinfo and gmake build-system wouldn't be so interwoven. when you get an error in mdoc, builds continue to build.
It's incredible frustrating to point out mistakes in documentation writing syntax.

2:
We already apply styling as far as I know?
Can you expand on what you mean?
Please also note that I'm going to add some notes on how I like to keep flawless automatic conversion to mdoc, and to remove version requirements on texinfo (locally, not pushed so far).

3:
The gnunet-c-tutoral isn't online so far.
For an initial website, docs.gnunet.org is okay. In the long-run I want to have a landing page similar to taler docs (for example also include an html output of mandoc html rendering of our manpages because apparently younger generations no longer are aware of the man command, etc).

ng0

2019-01-27 15:23

developer   ~0013480

Expanding 1:
I wanted to express that I don't think CI will solve anything for docs. Building the docs html output via CI would be good nevertheless.

dvn

2019-01-28 21:08

developer   ~0013502

Last edited: 2019-01-28 21:08

View 2 revisions

> I wanted to express that I don't think CI will solve anything for docs. Building the docs html output via CI would be good nevertheless.

What is the actual "problem" with the docs? Is there an issue filed?

ng0

2019-01-28 21:10

developer   ~0013503

What do you mean?

ng0

2019-01-28 21:17

developer   ~0013504

Expanding on this: some of these tickets opened because I was asked to are no issues.
I think Christian asked me to open them as working tasks, goals, etc.

dvn

2019-01-28 22:45

developer   ~0013505

> What do you mean?

Well you said in comment 0005121:0013480 that you "don't think CI will solve anything for docs" - What does that mean? What is there to solve for docs?

ng0

2019-01-28 23:10

reporter   ~0013509

to keep it short, people keep making Texinfo syntax mistakes. without any automated integration someone has to fix it every time this happens because the makeinfo is part of the standard gmake run.

CI alone won't solve this. Is this CD what we want here?

I thought I expressed this before.
Anyway, automatic generating the documentation page is necessary. No idea how we arrived here.

Christian Grothoff

2019-02-10 17:02

manager   ~0013643

I've just fixed the cron job at handbook (it was going into the wrong directory), improved the CSS based on what Emacs uses, and added tutorial.gnunet.org for the tutorial. I think that fixes this bug.

ng0

2019-02-10 22:16

reporter   ~0013646

Last edited: 2019-02-10 22:16

View 2 revisions

Thanks!

This is a short-term fix I hope? Having multiple domains for each documentation related part seems not really user friendly.

I was envisioning more of a docs landing page once we have it, where every document is linked (,maybe even including the bibliography I'm still working on).

Christian Grothoff

2019-02-10 22:19

manager   ~0013647

I agree that a landing page would be nice. In fact, I would want the PDF and other formats to be made available from such a landing page as well.

So yes, consider it a short-term fix until someone makes a nice landing page. (Maybe the landing page should go to gnunet.org/en/documentation.html, so it is internationalized?)

Issue History

Date Modified Username Field Change
2017-08-18 14:36 ng0 New Issue
2017-08-18 14:37 ng0 Summary gnunet.org: create docs.gnunet.org where the documentation is available => gnunet.org: create docs.gnunet.org where the documentation is available, and further actions
2017-08-18 14:38 ng0 Description Updated View Revisions
2017-08-24 10:51 ng0 Note Added: 0012389
2017-08-24 12:54 ng0 Note Added: 0012390
2017-08-24 12:55 ng0 Note Edited: 0012390 View Revisions
2017-08-24 13:17 ng0 Note Added: 0012391
2017-08-24 13:18 ng0 Assigned To => Christian Grothoff
2017-08-24 13:18 ng0 Status new => feedback
2017-09-27 20:13 ng0 Relationship added child of 0005140
2017-09-27 20:19 ng0 Relationship added child of 0005141
2017-10-04 15:21 Christian Grothoff Note Added: 0012459
2017-10-04 15:22 Christian Grothoff Assigned To Christian Grothoff => ng0
2017-10-28 23:47 ng0 Note Added: 0012524
2017-11-04 16:35 ng0 Note Added: 0012549
2017-11-04 16:36 ng0 Assigned To ng0 => Christian Grothoff
2017-11-04 16:37 ng0 Note Added: 0012550
2017-11-04 16:37 ng0 Status feedback => assigned
2017-11-04 16:39 ng0 Note Edited: 0012550 View Revisions
2017-11-04 17:09 Christian Grothoff Note Added: 0012551
2017-11-04 17:21 ng0 Note Added: 0012552
2017-11-04 20:59 ng0 Note Added: 0012562
2017-11-04 21:21 ng0 Note Added: 0012563
2018-01-07 20:22 ng0 Note Added: 0012737
2018-06-07 00:54 Christian Grothoff Assigned To Christian Grothoff =>
2018-06-07 00:54 Christian Grothoff Status assigned => confirmed
2018-06-07 00:54 Christian Grothoff Product Version => SVN HEAD
2018-06-07 00:54 Christian Grothoff Target Version => 0.11.0
2018-06-28 10:36 Christian Grothoff Note Added: 0013100
2018-06-28 11:55 ng0 Note Added: 0013103
2018-10-30 19:15 ng0 Relationship deleted child of 0005141
2019-01-26 06:02 Christian Grothoff Note Added: 0013467
2019-01-27 11:06 catonano Tag Attached: documentation
2019-01-27 15:22 ng0 Note Added: 0013479
2019-01-27 15:23 ng0 Note Added: 0013480
2019-01-28 21:08 dvn Note Added: 0013502
2019-01-28 21:08 dvn Note Edited: 0013502 View Revisions
2019-01-28 21:10 ng0 Note Added: 0013503
2019-01-28 21:17 ng0 Note Added: 0013504
2019-01-28 22:45 dvn Note Added: 0013505
2019-01-28 23:10 ng0 Note Added: 0013509
2019-02-10 17:02 Christian Grothoff Note Added: 0013643
2019-02-10 17:03 Christian Grothoff Assigned To => Christian Grothoff
2019-02-10 17:03 Christian Grothoff Status confirmed => resolved
2019-02-10 17:03 Christian Grothoff Resolution open => fixed
2019-02-10 17:03 Christian Grothoff Fixed in Version => 0.11.0
2019-02-10 22:16 ng0 Status resolved => feedback
2019-02-10 22:16 ng0 Resolution fixed => reopened
2019-02-10 22:16 ng0 Note Added: 0013646
2019-02-10 22:16 ng0 Note Edited: 0013646 View Revisions
2019-02-10 22:19 Christian Grothoff Note Added: 0013647
2019-02-10 22:19 Christian Grothoff Status feedback => resolved
2019-02-10 22:19 Christian Grothoff Resolution reopened => fixed
2019-02-28 11:17 Christian Grothoff Status resolved => closed