View Issue Details
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0005121||GNUnet||webpage||public||2017-08-18 14:36||2019-02-28 11:17|
|Reporter||ng0||Assigned To||Christian Grothoff|
|Priority||normal||Severity||minor||Reproducibility||have not tried|
|Product Version||SVN HEAD|
|Target Version||0.11.0||Fixed in Version||0.11.0|
|Summary||0005121: 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.
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.
> 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.
||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.|
||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.|
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.
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?
where $NAME is the software, holds the documentation.
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.
||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.|
> 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.
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.
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.
||docs.gnunet.org is online. bib.gnunet.org can be quickly put online once we have the generator ready somewhere.|
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/
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).
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.
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).
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).
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.
> 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?
||What do you mean?|
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.
> 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?
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.
||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.|
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).
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?)
|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|