Evan Welsh ewlsh // rockon999

Monday Markdown

Monday Markdown #1:

Rewriting the Development Experience for GNOME Javscript

Greetings World 😊

A lot has happened over the past few weeks!

I’ve spent the first portion of the coding period focused on improving the documentation browser for GNOME Javascript. In 2015/16 ptomato began porting GIR sources (the source of most GJS documentation) to [DevDocs.io], an open-source documentation browser, using g-ir-doc-tool in gobject-introspection. He did excellent work and produced a functioning product that now lives at [devdocs.baznga.org]. My goals were to take the current product and incorporate GNOME theming, fix issues with incorrect documentation, rebase the project on upstream, and reorient some of the project’s features to better serve an object oriented and GNOME model.

The first task I began was rebasing the project on upstream. Our fork was approx. 500 commits behind upstream, commits which included critical back-end fixes and front-end compatibility work. The merge introduced several bugs that took a few days to iron out. One CoffeeScript file ended up with a subtle arrow function syntax error that changed execution and broke some documentation loading, the Ruby on Rails routing was broken, etc.

After the project was rebased, I began the GNOME-ification process!

I began to introduce a GNOME-inspired theme (both from gnome.org and the GNOME HIG), working off this mockup:

Mockup of GNOME DevDocs Theme

I first began removing some absolute positioning from upstream’s front-end. Absolute positioning was used for numerous core elements instead of using modern solutions such as display: flex. This hindered easy design iteration as any minute change was liked to break another element. The numerous changes which I intended to implement in the new theme also functioned better in a responsive, flex layout.

First Iteration

Here you can see several improvements. Primarily, dropdowns have been eliminated when unnecessary, the header had been redesigned in a GNOME fashion, search has become a drop-down, and “enabled” vs. “disabled” has become “favorited” vs. “all”. The primary goal of the former changes was to make the site feel “GNOME-y”, the latter change was to make all the documentation accessible. For our purposes it made more sense to make everything visible than to disable some documentations and then force users to enable them to search, view, and utilize them.

Second Iteration

Here you can see that index pages for sources are now sorted by type instead of a simple alphabetical listing.

Third Iteration

In the third iteration there are many subtle CSS fixes, search has been made permanent instead of a dropdown (some user testing indicated the dropdown was confusing/less helpful). Here you can also see that we’ve removed “duplicate” entries and removed the namespace prefixes. Both of these changes make the site more usable and object-oriented friendly.

  • Duplicate entries occured where the “type” was merely an index of the functions and classed for a specific strings. See below for an illustration.

Problem with duplicate entries

Under the hood, at this point we made several more improvements. The repository utilized the stable branch (currently gnome-3-28) of gobject-introspection along with patches to properly format documentation for DevDocs. In gobject-introspection I also fixed long-standing bugs that made methods that were not introspectable and thus not in GJS show in class documentation. The docker instance was also upgraded and version-fixed so it would not break do to dependency errors in the future.

I think that’s it for this Monday Markdown, I’ll see you next week.

Evan // rockon999 // ewlsh

find me on matrix under rockon999.