W01: Boostrapping
I spent the first week of the GSoC recreating the Documenter HTML front end theme with the Bootstrap framework. The mockup is available here:
and the HTML / Sass / JS source is available here.
It is still a work in progress, in that there is still a lot of tweaking to do. I feel that I am not always using the framework in an idiomatic way yet, so those things should be identified and fixed. Also, the theme, the JS widgets and simply how the main Sass file is organized simply needs tweaking and cleanup.
A few additional disparate comments:
The CSS is built using Sass files, and makes use of variables etc. Where possible, I have used the variables Bootstrap provides, but I also needed to define some of my own.
A lesson I am taking away is that we definitely want to use Sass. Being able to use variables for defining the style makes the process of writing a theme much nicer. This is especially important for providing an easier way for users to create their own custom styles.
It does create a compilation step in the build, but the idea here is to have the necessary tooling to make that easy live in DocumenterTools.
I attempted to keep custom styling to a minimum and rely on Bootstrap for most things instead.
I've added a small JS widget which, if the site name in the sidebar is too long, resizes the font for that such that is would fit in the sidebar.
In some places I am still relying on custom CSS though:
- Currently admonitions are styled with custom CSS, but they should be replaced with cards if we want the style to be idiomatic Bootstrap.
- It might also be possible to use cards for docstrings, but footnotes most likely still need custom CSS.
- The sidebar is completely custom since, as far as I can tell, Bootstrap does not offer a way to really achieve the UX where the sidebar would enter from the side on a small screen, as we have now.
- The top bar (with the breadcrumb, GitHub link etc) is still using a custom flexbox styling, but I need to investigate if I can switch it over to using the flex layout classes.
Generic HTML
There is one aspect of Bootstrap's design philosophy that may become an issue for Documenter though. In general, you need to apply CSS classes to style an element, instead of relying on the semantic meaning of the HTML tag itself.
For example, to get your table to use Bootstrap, you need to apply the table class (i.e. the HTML must be <table class="table">). A simple <table> does not get styled by Bootstrap.
This is not a problem if you have full control over your HTML. But Documenter is also emitting raw HTML from arbitrary show(::MIME"text/html") methods (e.g. outputting a DataFrame in an @example block). There is no reason to expect that the HTML we are getting from these methods will include the correct classes and there is no (easy and reliable) way for us to fix it in Documenter.
The Bulma framework might have a way around this issue. While it generally also relies on CSS classes, it also provides the content class. You apply that to a container surrounding the HTML that does not have the appropriate classes and all the elements should still be styled properly, even though they do not have any classes themselves. In our case, the container would be the <article> that wraps the Markdown page content.
I should also check whether Semantic UI suffers from the same problem. Their documentation implies that they do apply some "baseline parameters" site-wide, but it is unclear from the documentation if this also includes things like block quotes and tables.
Next week
Now, since I also want to explore other CSS frameworks, it is not worth polishing the Bootstrap mockup too much. I also want to start thinking more about how to actually implement all of this in Documenter. With those things in mind, the goals for the second week are:
- Check out the feasibility of using Semantic UI
- Implement front end mockup in Bulma
- Start designing the user-facing APIs and figure out how much I need to refactor the existing Documenter code.