# [MRG+1] Updates entire website design #14849

Merged
merged 155 commits into from Sep 21, 2019
Merged

# [MRG+1] Updates entire website design#14849

merged 155 commits into from Sep 21, 2019

## Conversation

Member

### thomasjpfan commented Aug 30, 2019 • edited

 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! :)
added 13 commits Aug 29, 2019
 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 
reviewed
doc/templates/documentation.html Outdated Show resolved Hide resolved
Member

### jnothman commented Aug 30, 2019

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

### rth commented Aug 30, 2019 • edited

 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.
Member

### rth commented Aug 30, 2019

 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.
Member

### rth commented Aug 30, 2019 • edited

 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.
added 9 commits Aug 30, 2019
 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 
Member Author

### thomasjpfan commented Aug 30, 2019

 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.
added 2 commits Aug 30, 2019
 ENH Adds back links to other versions [doc build] 
 05786cb 
 ENH Padding to search results [doc build] 
 656572d 
Member

Member

### GaelVaroquaux commented Sep 18, 2019

 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.
reviewed
Member

### jnothman left a comment

 Otherwise, good to merge!! Wow, @thomasjpfan
doc/conf.py Outdated
 @@ -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')

#### jnothman Sep 18, 2019

Member

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

#### thomasjpfan Sep 20, 2019

Author Member

Removed.

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

#### jnothman Sep 18, 2019

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


Quick Start

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

#### jnothman Sep 18, 2019

Member
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.



API

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.

#### jnothman Sep 18, 2019

Member
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.



Classification

Identifying to which category an object belongs to.

#### jnothman Sep 18, 2019

Member
Suggested change


Identifying to which category an object belongs to.

Identifying which category an object belongs to.

#### jnothman Sep 18, 2019

Member

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 Sep 18, 2019

Member

(this seems to be a poor link target)

#### thomasjpfan Sep 20, 2019 • edited

Author Member

Poor as in...its too small?

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

Member

#### thomasjpfan Sep 20, 2019

Author Member

It meant to "Hide"

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

#### jnothman Sep 18, 2019

Member

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

#### thomasjpfan Sep 20, 2019

Author Member

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

#### thomasjpfan Sep 20, 2019

Author Member

This was changed to true.

 {% endif %}

#### jnothman Sep 18, 2019

Member

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

#### thomasjpfan Sep 20, 2019

Author Member

This reduces the number of HTTP requests.

#### thomasjpfan Sep 20, 2019

Author Member

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

and others added 5 commits Sep 20, 2019
 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 
Member

### GaelVaroquaux commented Sep 21, 2019

 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.
 DOC Adds getting started [doc build] 
 0478a28 
merged commit 89332d3 into scikit-learn:master Sep 21, 2019
19 checks passed
19 checks passed
LGTM analysis: C/C++ No code changes detected
Details
LGTM analysis: JavaScript No new or fixed alerts
Details
LGTM analysis: Python No new or fixed alerts
Details
ci/circleci: deploy Your tests passed on CircleCI!
Details
ci/circleci: doc Your tests passed on CircleCI!
Details
ci/circleci: doc artifact Link to 0/doc/_changed.html
Details
ci/circleci: doc-min-dependencies Your tests passed on CircleCI!
Details
ci/circleci: lint Your tests passed on CircleCI!
Details
codecov/patch Coverage not affected when comparing b02217d...0478a28
Details
codecov/project 96.76% (+<.01%) compared to b02217d
Details
scikit-learn.scikit-learn Build #20190921.2 succeeded
Details
scikit-learn.scikit-learn (Linux py35_conda_openblas) Linux py35_conda_openblas succeeded
Details
scikit-learn.scikit-learn (Linux py35_ubuntu_atlas) Linux py35_ubuntu_atlas succeeded
Details
scikit-learn.scikit-learn (Linux pylatest_conda_mkl) Linux pylatest_conda_mkl succeeded
Details
scikit-learn.scikit-learn (Linux pylatest_pip_openblas_pandas) Linux pylatest_pip_openblas_pandas succeeded
Details
scikit-learn.scikit-learn (Linux32 py35_ubuntu_atlas_32bit) Linux32 py35_ubuntu_atlas_32bit succeeded
Details
scikit-learn.scikit-learn (Windows py35_pip_openblas_32bit) Windows py35_pip_openblas_32bit succeeded
Details
scikit-learn.scikit-learn (Windows py37_conda_mkl) Windows py37_conda_mkl succeeded
Details
scikit-learn.scikit-learn (macOS pylatest_conda_mkl) macOS pylatest_conda_mkl succeeded
Details
Member

### jnothman commented Sep 21, 2019

 Awesome work, @thomasjpfan!
Member

### amueller commented Sep 23, 2019

 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.
Member

### amueller commented Sep 23, 2019

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

### amueller commented Sep 23, 2019

 also weird line-wrap:
Member

### amueller commented Sep 23, 2019

 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.
Member Author

### thomasjpfan commented Sep 23, 2019

 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.
mentioned this pull request Sep 23, 2019
Member

### amueller commented Sep 23, 2019

 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.
Member

### amueller commented Sep 23, 2019

 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.
Member Author

### thomasjpfan commented Sep 23, 2019

 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.
Member

### amueller commented Sep 23, 2019

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

### ogrisel commented Oct 2, 2019

 Same feeling.
Member Author

### thomasjpfan commented Oct 5, 2019

 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)
reviewed

#### lesteve Oct 19, 2019

Member

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.

Member

### GaelVaroquaux commented Oct 23, 2019

 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?
Member

### lesteve commented Oct 23, 2019

 Should we consider backporting this to sphinx-gallery? Sounds like a good idea indeed.
mentioned this pull request Oct 25, 2019
mentioned this pull request Nov 2, 2019