[MRG+1] Updates entire website design #14849

thomasjpfan · 2019-08-30T05:20:53Z

Here is a hosted version that follows this PR.

This PR:

Updates the entire design of the website.
Keeps all features from the original website.
Adds custom sidebar with button on the lower left. (Mobile friendly)
Completely custom sphinx theme that does not inherit from basic. There were a bunch of js/css we did not use, this is no longer loaded.
There are no images in the new theme.
Small images were generated for the logos on the bottom of the page in the index.
Uses bootstrap 4.

Enjoy! :)

…strap

doc/templates/documentation.html

jnothman · 2019-08-30T07:20:01Z

Wow! Loving it. I like the "minimal change to get it working" approach

rth · 2019-08-30T08:21:48Z

Very impressive @thomasjpfan !

Completely custom sphinx theme

I think overall this is great, though if we can afford a professional web-designer (cc @amueller) at least to review this and maybe propose some improvements on top this PR it would be ideal. Personally, I can say that the rendering looks good for me, but I really don't know to review it (with respect to cross-browser compatibility, best web-design practices etc). @cmarmo was also working on improving the website and if there is a way to collaborate on it somehow it would be great.

A side note, do we want to bundle minified jquery and bootstrap (as opposed to using a CDN)? I get they this allows to use the doc offline, but they are not that small and a prone to be updated frequently.

rth · 2019-08-30T08:26:31Z

For instance, I also wonder if bootstrap is still the best way to go in the frontend world. Though I agree it's a clear improvement over our current website in any case.

rth · 2019-08-30T08:27:43Z

For instance, I also wonder if bootstrap is still the best way to go in the frontend world. Though I agree it's a clear improvement over our current website in any case.

FWIW, pytorch also uses bootstrap but their theme is very customized.

thomasjpfan · 2019-08-30T15:48:03Z

Personally, I can say that the rendering looks good for me, but I really don't know to review it

Not having something like webpack to do auto prefixing is a little rough. I have been developing in firefox/chrome/safari. (edge is moving to chromium) I will get my hands on IE and see what it looks like.

FWIW, pytorch also uses bootstrap but their theme is very customized.

They vendor their bootstrap as well and not use the bootstrap CDN. (It is pretty nice to view docs locally)

For instance, I also wonder if bootstrap is still the best way to go in the frontend world. Though I agree it's a clear improvement over our current website in any case.

Bootstrap is really nice to prototype design in because I was most familiar with it. Now that we have a design, I think it is possible to use something smaller, like purecss. We would only need custom js for the "who uses scikit-learn" carousel and maybe for the navbar folding in mobile. Although, using a familiar/popular css framework like Bootstrap makes it easier for others to contribute/modify.

ogrisel · 2019-09-18T08:17:28Z

@jnothman any further comments? merge?

GaelVaroquaux · 2019-09-18T10:46:32Z

One last thing ;). I think that it is useful to add a max-width: 100% rule on the images of the body. On small devices, these can cause horizontal scroll. Horizontal scroll is particularly a problem because the burger menu of the top bar becomes hidden.

jnothman

Otherwise, good to merge!!

Wow, @thomasjpfan

jnothman · 2019-09-18T10:37:49Z

doc/conf.py

@@ -314,8 +309,8 @@ def make_carousel_thumbs(app, exception):

 def setup(app):
    # to hide/show the prompt in code examples:
-    app.add_javascript('js/copybutton.js')
-    app.add_javascript('js/extra.js')
+    # app.add_javascript('js/copybutton.js')


What's this about? I don't thnk we should have commented-out code lying around

jnothman · 2019-09-18T10:41:27Z

doc/templates/documentation.html

@@ -0,0 +1,111 @@
+{% extends "layout.html" %}
+{% set title = 'Documentation scikit-learn: machine learning in Python' %}


Suggested change

{% set title = 'Documentation scikit-learn: machine learning in Python' %}

{% set title = 'Documentation of scikit-learn: machine learning in Python' %}

jnothman · 2019-09-18T10:41:47Z

doc/templates/documentation.html

+      <div class="card h-100 sk-documentation-index-card mx-md-2">
+        <a href="{{ pathto('tutorial/basic/tutorial') }}" class="stretched-link sk-documentation-index-anchor"></a><h4 class="card-header">Quick Start</h4>
+        <div class="card-body p-3">
+          <p class="card-text">A very short introduction into machine learning problems and how to solve them using scikit-learn. Presents basic concepts and conventions.</p>


Suggested change

A very short introduction into machine learning problems and how to solve them using scikit-learn. Presents basic concepts and conventions.

A very short introduction to machine learning problems and how to solve them using scikit-learn. Presents basic concepts and conventions.

jnothman · 2019-09-18T10:43:25Z

doc/templates/documentation.html

+      <div class="card h-100 sk-documentation-index-card mx-md-2">
+        <a href="{{ pathto('modules/classes') }}" class="stretched-link sk-documentation-index-anchor"></a><h4 class="card-header">API</h4>
+        <div class="card-body p-3">
+          <p class="card-text">The exact API of all functions and classes, as given by the docstrings. The API documents expected types and allowed features for all functions, and all parameters available for the algorithms.</p>


Suggested change

The exact API of all functions and classes, as given by the docstrings. The API documents expected types and allowed features for all functions, and all parameters available for the algorithms.

The exact API of all functions and classes, as given by the docstrings. The API describes expected types and allowed features for all functions, and all parameters available for the algorithms.

"The API documents" was a garden path sentence, since "documents" is ambiguously a noun and verb.

jnothman · 2019-09-18T10:44:42Z

doc/templates/index.html

+      <div class="card h-100">
+        <div class="card-body">
+          <a href="supervised_learning.html#supervised-learning"><h4 class="sk-card-title card-title">Classification</h4></a>
+          <p class="card-text">Identifying to which category an object belongs to.</p>


Suggested change

Identifying to which category an object belongs to.

Identifying which category an object belongs to.

Yes, these are typos in the original.

I'd like to change these all to imperative mod: "Identify which category..." but perhaps in the next PR.

jnothman · 2019-09-18T10:48:16Z

doc/templates/index.html

+        <a class="btn btn-warning btn-big sk-donate-btn mb-1" onclick="document.getElementById('paypal-form').submit(); ">Help us, <strong>donate!</strong></a>
+        <a class="btn btn-warning btn-big mb-1" href="about.html#citing-scikit-learn"><strong>Cite us!</strong></a>
+        <p class="mt-2">
+            <a href="about.html#funding">Read more about donations</a>


(this seems to be a poor link target)

Poor as in...its too small?

jnothman · 2019-09-18T10:50:01Z

doc/themes/scikit-learn-modern/javascript.html

+	});
+
+{%- if pagename != 'index' and pagename != 'documentation' %}
+  /*** Had navbar when scrolling down ***/


What is "Had navbar"?

It meant to "Hide"

jnothman · 2019-09-18T10:53:47Z

doc/themes/scikit-learn-modern/theme.conf

+stylesheet = css/theme.css
+
+[options]
+google_analytics = false


I'm confused about this. It seems to be in contradiction to conf.py

This sets the default. I can change it to true by default.

This was changed to true.

jnothman · 2019-09-18T10:57:42Z

doc/themes/scikit-learn-modern/javascript.html

+{% endif %}
+
+<script>
+$(document).ready(function() {


Why is it preferably to include this in the page, rather than by src?

This reduces the number of HTTP requests.

The total number of bytes the javascript.html is small (in bytes), so I thought it was worth it to inline the javascript.

…strap

GaelVaroquaux · 2019-09-21T02:23:03Z

LGTM.

Merge? @jnothman : you had comments. I'll leave you some time to voice any other comments if you have some. If I don't hear from you, I'll merge.

jnothman · 2019-09-21T10:22:54Z

Awesome work, @thomasjpfan!

amueller · 2019-09-23T15:46:37Z

Sorry I didn't follow the discussion.
If I click on "install" the sidebar has a toc of install, and similarly for examples and API. But if I click on User Guide, the sidebar has a toc for the full page that includes the API and examples. That's a bit confusing. Here the sidebar doesn't correspond to the things on the left (which kind of makes sense since you don't want to show the same thing twice), but I find it confusing.

amueller · 2019-09-23T15:47:26Z

also, the "documentation" page now seems a bit useless, right?

amueller · 2019-09-23T15:48:36Z

also weird line-wrap:

amueller · 2019-09-23T15:51:11Z

Also, I would maybe remove the testimonials. They are mostly confusing if anything. Linking to the sklearn consortium or the google scholar citations would be more informative, I think.

thomasjpfan · 2019-09-23T15:53:19Z

If I click on "install" the sidebar has a toc of install, and similarly for examples and API. But if I click on User Guide, the sidebar has a toc for the full page that includes the API and examples. That's a bit confusing. Here the sidebar doesn't correspond to the things on the left (which kind of makes sense since you don't want to show the same thing twice), but I find it confusing.

The sidebar changes based on context. Before the sidebar was just useless: https://scikit-learn.org/stable/user_guide.html

also, the "documentation" page now seems a bit useless, right?

It is less useful now. It still gives a little context to each link.

amueller · 2019-09-23T18:45:31Z

There has been a discussion on how to structure numpy, scipy and pandas websites here:
numpy/numpy.org#43

It might make sense to join the discussion and/or follow suite.

amueller · 2019-09-23T20:31:09Z

It is less useful now. It still gives a little context to each link.

well but when/how would a user end up there? like if they don't know what of the other links to click? seems like a strange path to take.

thomasjpfan · 2019-09-23T20:55:16Z

well but when/how would a user end up there

They can end up there from the landing page if they click "Documentation":

well but when/how would a user end up there? like if they don't know what of the other links to click? seems like a strange path to take.

It kind of serves as a global index. I am okay with removing it.

amueller · 2019-09-23T21:00:23Z

Ah, I hadn't seen that. I'm not opposed to keeping it but it seems less useful now.

ogrisel · 2019-10-02T08:46:23Z

Same feeling.

thomasjpfan · 2019-10-05T17:46:04Z

One of the ways we are using the documentation page is to outline all the versions in the all versions page (It shows the version number on the top of the page)

lesteve · 2019-10-19T15:30:16Z

doc/themes/scikit-learn-modern/static/css/theme.css

+
+
+@media screen and (min-width: 1540px) {
+  .sphx-glr-download-link-note {


Great stuff! I just noticed that the note about the binder link is floated right, I wish I had the web skills to think of this in the first place and then execute it as well.

GaelVaroquaux · 2019-10-23T15:28:36Z

Great stuff! I just noticed that the note about the binder link is floated right, I wish I had the web skills to think of this in the first place and then execute it as well.

Should we consider backporting this to sphinx-gallery?

lesteve · 2019-10-23T16:58:17Z

Should we consider backporting this to sphinx-gallery?

Sounds like a good idea indeed.

thomasjpfan added 13 commits August 29, 2019 00:05

WIP

966bff8

WIP

108046d

WIP

1e7af43

WIP

61bc8a4

DOC Updates website design

baf6cc3

Merge remote-tracking branch 'upstream/master' into scikit-learn-boot…

9802914

…strap

REV

3c7425e

STY Fix

707cbeb

TST [doc build]

ca0d534

REV No logos

f489304

TST [doc build]

08ed442

DOC Adjust z-index of nav

e893b33

ENH Mobile first search [doc build]

bd58d82

jnothman reviewed Aug 30, 2019

View reviewed changes

doc/templates/documentation.html Outdated Show resolved Hide resolved

thomasjpfan added 9 commits August 30, 2019 08:12

BUG Fixes

e06ccdd

BUG Style fixes

c119892

ENH Does not load mathjax in index

8df63a8

ENH Whatsnew badges

d76b220

TST [doc build]

dfb7998

ENH Enhances image display [doc build]

af8e709

ENH Fixes headerlink jumping [doc build]

776b130

ENH Increases constrast between sidebar and main [doc build]

912522f

ENH Table style fix [doc build]

686aa8f

thomasjpfan added 2 commits August 30, 2019 12:00

ENH Adds back links to other versions [doc build]

05786cb

ENH Padding to search results [doc build]

656572d

jnothman reviewed Sep 18, 2019

View reviewed changes

thomasjpfan and others added 5 commits September 20, 2019 15:27

CLN Address comments

06da033

TST [doc build]

f16659a

Avoid images overflowing horizontally on small screens (#12)

ce78c21

Merge remote-tracking branch 'upstream/master' into scikit-learn-boot…

41b85eb

…strap

TST [doc build]

5232b36

DOC Adds getting started [doc build]

0478a28

jnothman merged commit 89332d3 into scikit-learn:master Sep 21, 2019

thomasjpfan mentioned this pull request Sep 23, 2019

DOC Adjust style of the footer [doc build] #15066

Merged

lesteve reviewed Oct 19, 2019

View reviewed changes

thomasjpfan mentioned this pull request Oct 25, 2019

part of the landing page is in layout.html #13979

Closed

loftiskg mentioned this pull request Nov 2, 2019

[MRG] Prevent hyphenation in parameter description #15499

Merged

cmarmo mentioned this pull request Jul 12, 2023

DOC Update web site to pydata-sphinx theme. #26809

Closed

4 tasks

		@@ -0,0 +1,111 @@
		{% extends "layout.html" %}
		{% set title = 'Documentation scikit-learn: machine learning in Python' %}

	{% set title = 'Documentation scikit-learn: machine learning in Python' %}
	{% set title = 'Documentation of scikit-learn: machine learning in Python' %}

	<p class="card-text">A very short introduction into machine learning problems and how to solve them using scikit-learn. Presents basic concepts and conventions.</p>
	<p class="card-text">A very short introduction to machine learning problems and how to solve them using scikit-learn. Presents basic concepts and conventions.</p>

	<p class="card-text">The exact API of all functions and classes, as given by the docstrings. The API documents expected types and allowed features for all functions, and all parameters available for the algorithms.</p>
	<p class="card-text">The exact API of all functions and classes, as given by the docstrings. The API describes expected types and allowed features for all functions, and all parameters available for the algorithms.</p>

	<p class="card-text">Identifying to which category an object belongs to.</p>
	<p class="card-text">Identifying which category an object belongs to.</p>



		@media screen and (min-width: 1540px) {
		.sphx-glr-download-link-note {

[MRG+1] Updates entire website design #14849

[MRG+1] Updates entire website design #14849

Conversation

thomasjpfan commented Aug 30, 2019 • edited Loading

jnothman commented Aug 30, 2019 via email

rth commented Aug 30, 2019 • edited Loading

rth commented Aug 30, 2019

rth commented Aug 30, 2019 • edited Loading

thomasjpfan commented Aug 30, 2019

ogrisel commented Sep 18, 2019

GaelVaroquaux commented Sep 18, 2019 via email

jnothman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thomasjpfan Sep 20, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GaelVaroquaux commented Sep 21, 2019

jnothman commented Sep 21, 2019

amueller commented Sep 23, 2019

amueller commented Sep 23, 2019

amueller commented Sep 23, 2019

amueller commented Sep 23, 2019

thomasjpfan commented Sep 23, 2019

amueller commented Sep 23, 2019

amueller commented Sep 23, 2019

thomasjpfan commented Sep 23, 2019

amueller commented Sep 23, 2019

ogrisel commented Oct 2, 2019

thomasjpfan commented Oct 5, 2019

Choose a reason for hiding this comment

GaelVaroquaux commented Oct 23, 2019 via email

lesteve commented Oct 23, 2019

thomasjpfan commented Aug 30, 2019 •

edited

Loading

rth commented Aug 30, 2019 •

edited

Loading

rth commented Aug 30, 2019 •

edited

Loading

thomasjpfan Sep 20, 2019 •

edited

Loading