Jekyll-generated site

[rcurtin]

I spent a long time rewriting the documentation and building it into the same Jekyll base that @shikharbhardwaj set up. The result is this:

http://ensmallen.org/new-site/_site/

I've got it deployed there temporarily, but if we are agreed that this is overall a good thing, I'll go ahead and push the Jekyll sources into place, so that we can maintain Markdown instead (and have contributors write new Markdown instead of needing to write HTML).

@conradsnicta @zoq let me know what you think. I frankensteined parts of the old webpage into place, and rewrote the entire documentation in Markdown and added some more optimizers.

[zoq]

The code listings are off on my mobile phone:

Not sure that is easy to fix, or this is just on my phone.

[conradsnicta]

The updated docs looks nice. A few issues on the site itself:

• I suggest making the content section wider. Looks rather squashed on my laptop -- the margins on either side are too large.
• The links from the names on the developers page don't seem to work.

On the docs page (not thoroughly checked):

• in the Arbitrary functions section, incomplete/errant link: [#Differentiable_functions].
• in the Differentiable separable functions section, incomplete/errant link within the list of optimisers: [Stochastic Gradient Descent ...
• in the Optimizer documentation part, the tables with attributes use the same colour as used for links. This is potentially confusing, as the text colouring implies that stuff such as "stepSize", "bathSize" is clickable. I suggest using a different colour here, or simply using boldface instead of colouring.
• in the StochAstic Recusive gRadient algoritHm (SARAH/SARAH+) section, within the Examples subsection, the last comment (// Stochastic variance.. ) juts out beyond the grey background. This might be due to the font size setting on my browser, but for good measure the comment should be moved to just above the SARAH_Plus declaration.
• Similar problem as above in the Standard stochastic variance reduced gradient (SVRG) section, within the Examples subsection.
• Somewhere near the top, it would be useful to provide a link to the docs for armadillo Mat, Col, Row.

There are a few issues with the mobile version of the site (ie. when the browser window is sufficiently thin):

• The burger menu (on the right) has old content.
• When the browser window is shrunk, then the burger menu activated and not closed, and then browser window enlarged again, the menu doesn't disappear

[rcurtin]

I spent some time with CSS (or SCSS as it is with Jekyll) and I think I fixed the issue with too-long lines not having the grey background for code. I also changed the table formatting a bit so that it will avoid making them overwide by wrapping individual characters in words (kind of ugly but it is the best solution since some of the member types and names are very long...).

I fixed all the issues Conrad pointed out except one:

When the browser window is shrunk, then the burger menu activated and not closed, and then browser window enlarged again, the menu doesn't disappear

I can't seem to reproduce this. The minimum width for the burger menu / mobile mode is 940px so it should switch back over there. These are the default Jekyll themes so I'm not too inclined to screw with them too much. The HTML that's running right now has really nice mobile support but it looked like it would be trouble or time-consuming to try and adapt it so I just went with what Jekyll had.

If we think this is "good enough" for a first round, I can go ahead and merge it in and we can update it later perhaps. I'm also happy to iterate a bit more improving things.

[conradsnicta]

I can't seem to reproduce this. The minimum width for the burger menu / mobile mode is 940px so it should switch back over there. These are the default Jekyll themes so I'm not too inclined to screw with them too much. The HTML that's running right now has really nice mobile support but it looked like it would be trouble or time-consuming to try and adapt it so I just went with what Jekyll had.

It's a relatively minor issue in the grand scheme of things, but it may indicate other problems elsewhere. I manged to replicate this in Chrome as well. Exact steps:

1. maximise browser window
2. load ensmallen.org in new tab
3. grab browser title bar so that browser window is resizable; release browser title bar
4. shrink browser window horizontally until the burger menu appears on the top-right
5. click on burger menu so that "home, documentation + etc" appears
6. do not close the burger menu
7. maximise browser window
8. the menu stays on the right

If we think this is "good enough" for a first round, I can go ahead and merge it in and we can update it later perhaps. I'm also happy to iterate a bit more improving things.

Looks good. I'm also happy to iterate this bit by bit, eg. via PRs.

The one thing that stands out at the moment is the horizontal size of the Attributes tables. There is lots of horizontal white space which makes parsing the table a bit involved / annoying. This might be an "overfix" for the issue reported by marcus.

[rcurtin]

Oh, I see, the table-layout worked in a way I didn't expect. I've updated it now, but without the table-layout: fixed then it will often be too wide on mobile (or narrow) browsers. It doesn't look like that's easy to fix, so unless you know of a way to make it work I can work it in, or maybe we can just leave it for later (or maybe it's not really a problem anyway).

I think I fixed the menu problem (kind of)---basically I just wrote some CSS that does a display: none on the nav.menu-open class when the browser is wider than 920px. If you leave the menu open, make the site too wide, the menu will go away; but if you make it too small again, the menu pops back up. I don't think that's a huge issue.

[conradsnicta]

Seems to look ok now. I think the primary viewing platform for the documentation is a desktop, where people would actually use ensmallen for development. The mobile version is a bonus, in the "nice to have, but not super-important" sense.

[rcurtin]

Ok---I've updated the code in the repo and deployed the website. Maybe later I will set up the website so it rebuilds whenever everything is pushed, but we can wait on that one.

If anyone finds any issues with the site feel free to open another issue and I can try to handle it. :