ENH/DOC: pydata sphinx theme polishing by tupui · Pull Request #13814 · scipy/scipy

tupui · 2021-04-06T10:47:55Z

This is a follow up PR for #13724.

It Address the last comments from reviews and is a starting point for further improvement. Please propose any improvements here (or do a PR on my branch).

Things to check/do:

~~Icons: NumFOCUS, Tidelift, twitter?~~ Should be on the organization website, not here.
Polish the landing page
Polish Getting started
Google analytics?
PDF/zip download links needed? -> link to https://docs.scipy.org/doc/
General organization
Deployment of the doc: verify CI, scipyorg, make, etc. -> seems ok, devdoc is live
Developer instructions

justbennet · 2021-04-06T11:45:02Z

If possible, I suggest that the graphical icons be active links to the documentation as well as the 'To the documentation' text in the grey boxes. I believe most people would expect that behavior.

mdhaber · 2021-04-07T01:57:10Z

There has been some discussion of analytics at scipy/scipy.org#338.

tupui · 2021-04-07T13:09:12Z

There has been some discussion of analytics at scipy/scipy.org#338.

Thanks. Looking at it, there is still no decision. I just saw there are using google analytics in Pandas, hence my question.

mdhaber · 2021-04-07T13:36:16Z

Right, it's still a good question! There were some useful suggestions there, though, e.g. to use something other than Google analytics. Great for the discussion to continue; just thought it's best to see what has been said in the past.

tupui · 2021-04-07T16:36:54Z

@justbennet I added the clickable icons. The solution is not that fancy, I guess it's fine.

tupui · 2021-04-08T07:30:48Z

@jorisvandenbossche proposed to use sphinx-panels instead of the raw html. They are going with it in Pandas. Seems like the good choice here. I will update the PR with the suggestions he made.

tupui · 2021-04-08T21:25:00Z

We are again seeing some timeout in the CI. It's getting concerning.

Maybe we could do some caching of the builds? We could cache master and then all build times should be way faster. Or would this be problematic?

larsoner · 2021-04-12T14:13:23Z

Looks like there is a conflict. Feel free to ping me for a review when this is ready

tupui · 2021-04-12T15:26:57Z

Looks like there is a conflict. Feel free to ping me for a review when this is ready

Sorry I did not intentionally ping you (CODEOWNER thing got triggered). But I would still be happy to have your review 😃 . I don't think we are done here, we can continue to tweak things.

Current CI fails due to a scheduled maintenance from bintray: https://status.bintray.com/ (cc @rgommers in case)

larsoner · 2021-04-12T16:27:26Z

Sorry I did not intentionally ping you (CODEOWNER thing got triggered).

No problem, it was actually clear from the GitHub email that it was due to CODEOWNER and not you -- I just wanted to chime in to say that I'm happy to review when it's time!

tupui · 2021-04-13T13:20:11Z

Apparently it fails in Latex. I still don't know why. @jorisvandenbossche how did you solve this in Pandas? Is it because you use pdflatex and not latexmk? Apparently it is due to having the images in svg because in png it seems fine. This just started to appear with using the sphinx-panels extension (normal as before it was included as html I suppose).

ilayn · 2021-04-15T16:12:40Z

latexmk wants to run pdflatex twice but somehow something kicks off an xetex run with very old packages. Once I tried to fix that TeX run but always got lost or lost interest probably we have to get to the bottom of it as it is a massive part of doc builds (not so useful either imho).

tupui · 2021-04-15T17:04:08Z

latexmk wants to run pdflatex twice but somehow something kicks off an xetex run with very old packages. Once I tried to fix that TeX run but always got lost or lost interest probably we have to get to the bottom of it as it is a massive part of doc builds (not so useful either imho).

I am not a user of the PDF doc either. Would be interesting to have some statistics to know if this is really used...

As for now, I can fix the issue by using png images instead of svg if there is no obvious way.

tupui · 2021-04-20T09:28:11Z

Just seeing this now. mstats and qmc are doubled in the API's section's sidebar.

tupui · 2021-04-21T12:34:08Z

The issue is fixed and to try I set maxdepth=1 in the sidebar. Let me know what you think. This is making the html files smaller as intended.

larsoner · 2021-04-21T12:38:28Z

CircleCI is not happy:

./scipy-ref.tex:155: Unable to load picture or PDF file 'index_getting_started.

tupui · 2021-04-21T13:15:06Z

CircleCI is not happy:

./scipy-ref.tex:155: Unable to load picture or PDF file 'index_getting_started.

Thanks for reminding me! I will convert the svg to png (I tested this locally and it fixes the issue).

tupui · 2021-04-21T15:17:59Z

@larsoner now green 🥳 , but the images are stretched, have to tweak something here.

larsoner

Otherwise LGTM. Did you want to take care of other items at the top that aren't checked off yet, or should we merge this once the button is fixed?

tupui · 2021-04-21T19:33:05Z

Otherwise LGTM. Did you want to take care of other items at the top that aren't checked off yet, or should we merge this once the button is fixed?

Thanks for reviewing @larsoner. As for the other items, I just listed things I could think about, but I am not sure I am in the best position to propose more than what I did (the quick start guide for instance, not sure if this is enough or if we would want something different. Same for the sidebar, is this what we want in the end?), also my design skills are poor to say the least 😅. I hoped to catch a bit more maintainers here to work on this collectively.

jorisvandenbossche · 2021-04-22T06:17:23Z

  <div class="bd-toc-item active">
    {% if pagename.startswith("reference") %}
-    {{ generate_nav_html("sidebar", maxdepth=4, collapse=True, includehidden=True, titles_only=True) }}
+    {{ generate_nav_html("sidebar", maxdepth=2, collapse=True, includehidden=True, titles_only=True) }}


Suggested change

{{ generate_nav_html("sidebar", maxdepth=2, collapse=True, includehidden=True, titles_only=True) }}

{{ generate_nav_html("sidebar", maxdepth=1, collapse=True, includehidden=True, titles_only=True) }}

My previous comment was mainly about the user guide, I think you could keep it here at a maxdepth of 1 in the reference guide, because it's mainly here that you get such huge sidebars because of all individual docstring pages getting included.

Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com>

larsoner

LGTM +1 for merge

@jorisvandenbossche any other thoughts or comments?

If nobody else has comments I'll try to remember to merge on Monday.

larsoner · 2021-04-26T13:11:37Z

Thanks @tupui !

* master: (164 commits) DOC: Add Karl Pearson's reference to chi-square test (scipy#13971) BLD: fix build warnings for causal/anticausal pointers in ndimage MAINT: stats: Fix unused imports and a few other issues related to imports. DOC: fix typo MAINT: Remove duplicate calculations in sokalmichener BUG: spatial: fix weight handling of `distance.sokalmichener`. DOC: update Readme (scipy#13910) MAINT: QMCEngine d input validation (scipy#13940) MAINT: forward port 1.6.3 relnotes REL: add PEP 621 (project metadata in pyproject.toml) support EHN: signal: make `get_window` supports `general_cosine` and `general_hamming` window functions. (scipy#13934) ENH/DOC: pydata sphinx theme polishing (scipy#13814) DOC/MAINT: Add copyright notice to qmc.primes_from_2_to (scipy#13927) BUG: DOC: signal: fix need argument config and add missing doc link for `signal.get_window` DOC: fix subsets docstring (scipy#13926) BUG: signal: fix get_window argument handling and add tests. (scipy#13879) ENH: stats: add 'alternative' parameter to ansari (scipy#13650) BUG: Reactivate conda environment in init MAINT: use dict built-in rather than OrderedDict Revert "CI: Add nightly release of NumPy in linux workflows (scipy#13876)" (scipy#13909) ...

DOC: suggestions from review

272f7b2

rgommers reviewed Apr 6, 2021

View reviewed changes

Comment thread doc/source/index.rst Outdated

DOC: remove download links and clickable icons

1dc4f5c

tupui mentioned this pull request Apr 8, 2021

DOC: pydata sphinx theme #13724

Merged

DOC/ENH: use sphinx-panels

a71f4fb

DOC: captions in dev index using pydata theme 0.6

b76f214

tupui force-pushed the theme_design branch from 9936930 to 8602c6c Compare April 12, 2021 07:52

tupui requested a review from larsoner as a code owner April 12, 2021 07:52

tupui force-pushed the theme_design branch 2 times, most recently from 7400cba to 397d66f Compare April 12, 2021 15:12

tupui added 3 commits April 13, 2021 10:04

Merge remote-tracking branch 'upstream/master' into theme_design

5932932

MAINT: sphinx-panels to main environment.yml

de82188

DOC: sphinx-panels css

d68d45e

tupui force-pushed the theme_design branch from 397d66f to d68d45e Compare April 13, 2021 08:05

DOC: fix ref doc ambiguity for quick_start

93f7fb8

Merge remote-tracking branch 'upstream/master' into theme_design

13750c2

tupui mentioned this pull request Apr 20, 2021

DOC: BLD: fix doc build version check, and improve build time #13897

Merged

tupui added 3 commits April 21, 2021 12:21

Merge remote-tracking branch 'upstream/master' into theme_design

464ed88

DOC: remove duplicate modules qmc and mstats

926af71

DOC: maxdepth=1 in sidebar

1d13d51

DOC: replace svg with png in the index

95691d3

DOC: fix css for index images

1c2c91d

larsoner reviewed Apr 21, 2021

View reviewed changes

Comment thread doc/source/getting_started.rst

DOC: fix css custom-button

96b3335

jorisvandenbossche reviewed Apr 21, 2021

View reviewed changes

Comment thread doc/source/_templates/sidebar-nav-bs.html Outdated

jorisvandenbossche reviewed Apr 21, 2021

View reviewed changes

Comment thread doc/source/_static/scipy.css

tupui commented Apr 22, 2021

View reviewed changes

Comment thread doc/source/_static/scipy.css

Comment thread doc/source/_templates/sidebar-nav-bs.html

Comment thread doc/source/_templates/sidebar-nav-bs.html Outdated

Apply suggestions from code review

2cd7f36

jorisvandenbossche reviewed Apr 22, 2021

View reviewed changes

Apply suggestions from code review

0b40e4f

Co-authored-by: Joris Van den Bossche <jorisvandenbossche@gmail.com>

larsoner approved these changes Apr 23, 2021

View reviewed changes

larsoner merged commit be4c5ff into scipy:master Apr 26, 2021

tupui deleted the theme_design branch April 26, 2021 13:19

tupui mentioned this pull request Apr 26, 2021

REL: add PEP 621 (project metadata in pyproject.toml) support #13929

Merged

tylerjereddy added this to the 1.7.0 milestone Apr 27, 2021

	{{ generate_nav_html("sidebar", maxdepth=2, collapse=True, includehidden=True, titles_only=True) }}
	{{ generate_nav_html("sidebar", maxdepth=1, collapse=True, includehidden=True, titles_only=True) }}

Uh oh!

Conversation

tupui commented Apr 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

justbennet commented Apr 6, 2021

Uh oh!

mdhaber commented Apr 7, 2021

Uh oh!

tupui commented Apr 7, 2021

Uh oh!

mdhaber commented Apr 7, 2021

Uh oh!

tupui commented Apr 7, 2021

Uh oh!

tupui commented Apr 8, 2021

Uh oh!

tupui commented Apr 8, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

larsoner commented Apr 12, 2021

Uh oh!

tupui commented Apr 12, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

larsoner commented Apr 12, 2021

Uh oh!

tupui commented Apr 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ilayn commented Apr 15, 2021

Uh oh!

tupui commented Apr 15, 2021

Uh oh!

tupui commented Apr 20, 2021

Uh oh!

tupui commented Apr 21, 2021

Uh oh!

larsoner commented Apr 21, 2021

Uh oh!

tupui commented Apr 21, 2021

Uh oh!

tupui commented Apr 21, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

larsoner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tupui commented Apr 21, 2021

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jorisvandenbossche Apr 22, 2021

Choose a reason for hiding this comment

Uh oh!

larsoner left a comment

Choose a reason for hiding this comment

Uh oh!

larsoner commented Apr 26, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

tupui commented Apr 6, 2021 •

edited

Loading

tupui commented Apr 8, 2021 •

edited

Loading

tupui commented Apr 12, 2021 •

edited

Loading

tupui commented Apr 13, 2021 •

edited

Loading

tupui commented Apr 21, 2021 •

edited

Loading