Phasing out the current developer.gnome.org

--===============1271135668516197150==
Content-Type: multipart/alternative; boundary="000000000000128ee405c184d4a2"

--000000000000128ee405c184d4a2
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

Hi all;

this is going to be a long email, so please bear with me.

tl;dr: the current state of developer.gnome.org can be described, by and
large, with "a huge mess"; we need to phase out the existing stack, and I
have a good idea of how to make that happen.

On the technical side: library-web is a Python 2 application that is
basically tied to the way things have been done in the past. It requires
projects to ship a full render of their gtk-doc-based API reference in
their release archives=E2=80=94something that will be discarded by distribu=
tions
and users alike, and it's only needed for library-web; it also parses the
generated HTML to inject a different CSS (as if we didn't control gtk-doc
ourselves), and changes the cross-reference links to remove the absolute
paths to the maintainer's file system with URLs to developer.gnome.org.
Sadly, library-web is currently unmaintained; this means it cannot deal
with changes in our build systems (from Autotools to CMake or Meson, which
do not distribute the API reference in the release archive), or changes in
the tools we use to generate the API reference itself (from gtk-doc to
gi-docgen). I'll skip the fact that gtk-doc is also unmaintained, which
means stuff is breaking apart on multiple fronts.

From the perspective of a developer of a bunch of libraries in the core
GNOME stack the situation has slowly drifted from being broken to become
entirely untenable. Early this year I wrote an entirely new tool to replace
gtk-doc in order to generate the API reference of GTK4; while I'm being
clear that the goal of the tool is to document GTK and a couple of its
dependencies (like Pango and GdkPixbuf), I'm also aware that other projects
are looking at it to replace gtk-doc.

Of course, replacing gtk-doc means that library-web is currently unable to
even deal with it; I tried to modify library-web[1] to get it to publish
the documentation and leaving it alone, but it turns out that it's harder
than it looks, and it's even harder to gather logs out of our
infrastructure. I also tried to run a container with library-web on my
machine, to understand what it is doing, but in practice it's just a black
box. This led to the GTK project publishing the API reference on its own
gtk.org domain[2], though the CI pipeline, at least for the time being.

From the technical side, this Jenga pile. held together by hopes and
dreams, has to go away.

We build all our libraries to publish the GNOME run times anyway; ideally,
we should be publishing the `org.gnome.Sdk.Docs` run time, but that kind of
broke with the switch to Buildstream. I'm currently looking at ways to fix
that, and then publishing the API references of all our stack as part of
our build process, just like we publish releases and VM for GNOME OS. The
idea is to have a versioned area so you can ask for the API references for
GNOME 40, 41, etc. in the form of:

 - https://sdk.gnome.org/docs/nightly/
  - all bleeding edge builds from the main development branch
 - https://sdk.gnome.org/docs/40/
   - GTK 3.24: https://sdk.gnome.org/docs/40/gtk3/
   - GTK 4.2: https://sdk.gnome.org/docs/40/gtk4/
   - ...

This way you only ask for the documentation related to the version of the
GNOME SDK you want.

On the content side: there's a huge chunk of articles, guides, and
tutorials that are either written for GNOME 2 or early GNOME 3; they are
hard to update, hard to search for, and hard to contribute to.

The Design team is moving the HIG[3] to a Sphinx set up, which publishes
the rendered documentation through a CI pipeline on GitLab pages. I used
the same theme and set up to render the current developer.gnome.org in my
personal space:

  - https://gitlab.gnome.org/ebassi/developer-www/
  - https://ebassi.pages.gitlab.gnome.org/developer-www/index.html

I'm in the process of:

 - vetting the current content of developer.gnome.org, dropping the GNOME2
and early GNOME3 stuff
 - editing the programmers guide to drop outdated content
 - re-organising the accessibility and localisation guidelines into their
own sections, possibly moving some of the content into the HIG
 - re-organising the HowDoI wiki pages into proper tutorials, with the goal
of dropping them from the wiki

The audience is geared towards GNOME 40 and GTK4 as a baseline.

Ideally, I'd like to tweak the Sphinx output to point each page to its
location on the Git repository, so that it's possible to quickly edit the
content through the GitLab web UI. My experience with doing that on the
gtk.org website has been a net positive, with a good deal of engagement
from new contributors.

The end goal is to phase out the API references section of
developer.gnome.org, moving that to a new, auto-generated website built by
our CI/CD pipeline; the remaining content of developer.gnome.org will be
vetted, and refreshed, in order to be published on its own CI pipeline.

There is one last thing that library-web does, and it's: publishing the
GNOME release notes, the application help, and the administrators guide. I
think Shaun has some ideas on the application help, and we can probably
figure out a similar arrangement for the release notes (which have been
painful to deal with for a while, now) and the administrators guide.

I'm happy to talk specifics on the plan's outline, if people have questions=
.

Ciao,
 Emmanuele.

[1]: https://gitlab.gnome.org/Infrastructure/library-web/-/merge_requests/1=
6
[2]: https://docs.gtk.org
[3]: https://mail.gnome.org/archives/gnome-doc-list/2021-March/msg00008.htm=
l

--=20
https://www.bassi.io
[@] ebassi [@gmail.com]

--000000000000128ee405c184d4a2
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div>Hi all;</div><div><br></div><div>this is going to be =
a long email, so please bear with me.<br></div><div><br></div><div>tl;dr: t=
he current state of <a href=3D"http://developer.gnome.org">developer.gnome.=
org</a> can be described, by and large, with &quot;a huge mess&quot;; we ne=
ed to phase out the existing stack, and I have a good idea of how to make t=
hat happen.<br></div><div><br></div><div>On the technical side: library-web=
 is a Python 2 application that is basically tied to the way things have be=
en done in the past. It requires projects to ship a full render of their gt=
k-doc-based API reference in their release archives=E2=80=94something that =
will be discarded by distributions and users alike, and it&#39;s only neede=
d for library-web; it also parses the generated HTML to inject a different =
CSS (as if we didn&#39;t control gtk-doc ourselves), and changes the cross-=
reference links to remove the absolute paths to the maintainer&#39;s file s=
ystem with URLs to <a href=3D"http://developer.gnome.org">developer.gnome.o=
rg</a>. Sadly, library-web is currently unmaintained; this means it cannot =
deal with changes in our build systems (from Autotools to CMake or Meson, w=
hich do not distribute the API reference in the release archive), or change=
s in the tools we use to generate the API reference itself (from gtk-doc to=
 gi-docgen). I&#39;ll skip the fact that gtk-doc is also unmaintained, whic=
h means stuff is breaking apart on multiple fronts.<br></div><div><br></div=
><div>From the perspective of a developer of a bunch of libraries in the co=
re GNOME stack the situation has slowly drifted from being broken to become=
 entirely untenable. Early this year I wrote an entirely new tool to replac=
e gtk-doc in order to generate the API reference of GTK4; while I&#39;m bei=
ng clear that the goal of the tool is to document GTK and a couple of its d=
ependencies (like Pango and GdkPixbuf), I&#39;m also aware that other proje=
cts are looking at it to replace gtk-doc.</div><div><br></div><div>Of cours=
e, replacing gtk-doc means that library-web is currently unable to even dea=
l with it; I tried to modify library-web[1] to get it to publish the docume=
ntation and leaving it alone, but it turns out that it&#39;s harder than it=
 looks, and it&#39;s even harder to gather logs out of our infrastructure. =
I also tried to run a container with library-web on my machine, to understa=
nd what it is doing, but in practice it&#39;s just a black box. This led to=
 the GTK project publishing the API reference on its own <a href=3D"http://=
gtk.org">gtk.org</a> domain[2], though the CI pipeline, at least for the ti=
me being.</div><div><br></div><div>From the technical side, this Jenga pile=
. held together by hopes and dreams, has to go away.</div><div><br></div><d=
iv>We build all our libraries to publish the GNOME run times anyway; ideall=
y, we should be publishing the `org.gnome.Sdk.Docs` run time, but that kind=
 of broke with the switch to Buildstream. I&#39;m currently looking at ways=
 to fix that, and then publishing the API references of all our stack as pa=
rt of our build process, just like we publish releases and VM for GNOME OS.=
 The idea is to have a versioned area so you can ask for the API references=
 for GNOME 40, 41, etc. in the form of:</div><div><br></div><div>=C2=A0- <a=
 href=3D"https://sdk.gnome.org/docs/nightly/">https://sdk.gnome.org/docs/ni=
ghtly/</a></div><div>=C2=A0 - all bleeding edge builds from the main develo=
pment branch<br></div><div>=C2=A0- <a href=3D"https://sdk.gnome.org/docs/40=
/">https://sdk.gnome.org/docs/40/</a></div><div>=C2=A0=C2=A0 - GTK 3.24: <a=
 href=3D"https://sdk.gnome.org/docs/40/gtk3/">https://sdk.gnome.org/docs/40=
/gtk3/</a></div><div>=C2=A0=C2=A0 - GTK 4.2: <a href=3D"https://sdk.gnome.o=
rg/docs/40/gtk4/">https://sdk.gnome.org/docs/40/gtk4/</a></div><div>=C2=A0=
=C2=A0 - ...<br></div><div><br></div><div>This way you only ask for the doc=
umentation related to the version of the GNOME SDK you want.</div><div><br>=
</div><div><div>On the content side: there&#39;s a huge chunk of articles, =
guides, and tutorials that are either written for GNOME 2 or early GNOME 3;=
 they are hard to update, hard to search for, and hard to contribute to.<br=
></div><div><br></div><div>The Design team is moving the HIG[3] to a Sphinx=
 set up, which publishes the rendered documentation through a CI pipeline o=
n GitLab pages. I used the same theme and set up to render the current <a h=
ref=3D"http://developer.gnome.org">developer.gnome.org</a> in my personal s=
pace:</div><div><br></div><div>=C2=A0 - <a href=3D"https://gitlab.gnome.org=
/ebassi/developer-www/">https://gitlab.gnome.org/ebassi/developer-www/</a><=
/div><div>=C2=A0 - <a href=3D"https://ebassi.pages.gitlab.gnome.org/develop=
er-www/index.html">https://ebassi.pages.gitlab.gnome.org/developer-www/inde=
x.html</a></div></div><div><br></div><div>I&#39;m in the process of:</div><=
div><br></div><div>=C2=A0- vetting the current content of <a href=3D"http:/=
/developer.gnome.org">developer.gnome.org</a>, dropping the GNOME2 and earl=
y GNOME3 stuff</div><div>=C2=A0- editing the programmers guide to drop outd=
ated content<br></div><div>=C2=A0- re-organising the accessibility and loca=
lisation guidelines into their own sections, possibly moving some of the co=
ntent into the HIG<br></div><div>=C2=A0- re-organising the HowDoI wiki page=
s into proper tutorials, with the goal of dropping them from the wiki<br></=
div><div><br></div><div>The audience is geared towards GNOME 40 and GTK4 as=
 a baseline.<br></div><div><br></div><div>Ideally, I&#39;d like to tweak th=
e Sphinx output to point each page to its location on the Git repository, s=
o that it&#39;s possible to quickly edit the content through the GitLab web=
 UI. My experience with doing that on the <a href=3D"http://gtk.org">gtk.or=
g</a> website has been a net positive, with a good deal of engagement from =
new contributors.</div><div><br></div><div>The end goal is to phase out the=
 API references section of <a href=3D"http://developer.gnome.org">developer=
.gnome.org</a>, moving that to a new, auto-generated website built by our C=
I/CD pipeline; the remaining content of <a href=3D"http://developer.gnome.o=
rg">developer.gnome.org</a> will be vetted, and refreshed, in order to be p=
ublished on its own CI pipeline.</div><div><br></div><div>There is one last=
 thing that library-web does, and it&#39;s: publishing the GNOME release no=
tes, the application help, and the administrators guide. I think Shaun has =
some ideas on the application help, and we can probably figure out a simila=
r arrangement for the release notes (which have been painful to deal with f=
or a while, now) and the administrators guide.</div><div><br></div><div>I&#=
39;m happy to talk specifics on the plan&#39;s outline, if people have ques=
tions.<br></div><div><br></div><div>Ciao,</div><div>=C2=A0Emmanuele.<br></d=
iv><div><br></div><div>[1]: <a href=3D"https://gitlab.gnome.org/Infrastruct=
ure/library-web/-/merge_requests/16">https://gitlab.gnome.org/Infrastructur=
e/library-web/-/merge_requests/16</a></div><div>[2]: <a href=3D"https://doc=
s.gtk.org">https://docs.gtk.org</a><br></div><div>[3]: <a href=3D"https://m=
ail.gnome.org/archives/gnome-doc-list/2021-March/msg00008.html">https://mai=
l.gnome.org/archives/gnome-doc-list/2021-March/msg00008.html</a></div><div>=
<br>-- <br><div dir=3D"ltr" class=3D"gmail_signature" data-smartmail=3D"gma=
il_signature"><a href=3D"https://www.bassi.io" target=3D"_blank">https://ww=
w.bassi.io</a><br>[@] ebassi [@<a href=3D"http://gmail.com" target=3D"_blan=
k">gmail.com</a>]</div></div></div>

--000000000000128ee405c184d4a2--

--===============1271135668516197150==
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Content-Disposition: inline

_______________________________________________
gnome-doc-list mailing list
[email protected]
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

--===============1271135668516197150==--