📚 New theme & rearrangement of the docs #4835

andersy005 · 2021-01-21T04:17:33Z

Closes #xxxx
Passes pre-commit run --all-files
User visible changes (including notable bug fixes) are documented in whats-new.rst
New functions/methods are listed in api.rst

andersy005 · 2021-01-21T04:40:57Z

…cs/new-theme

andersy005 · 2021-02-03T18:14:37Z

@pydata/xarray, does anyone know what's going on with readthedocs: https://readthedocs.org/projects/xray/builds/12928622/? I can't seem to figure out the error causing the build failures.

keewis · 2021-02-03T18:22:08Z

that's because of the headings in whats-new.rst. I think you have to be consistent with the style you use (=, +, ~, -).

DocOtak · 2021-02-03T18:38:34Z

Also, the build step also has a -W flag which turns warnings into Errors and causes a non 0 exit status. This is probably because the read the docs config file for xarray has a fail_on_warning set to true

andersy005 · 2021-02-03T19:48:54Z

that's because of the headings in whats-new.rst. I think you have to be consistent with the style you use (=, +, ~, -).

Ah okay... ~~Is this issue connected to a specific sphinx version or readthedocs? I'm asking because I don't run into this issue locally~~

Edit: I was too quick to reply. 👍🏽 for @DocOtak's explanation (#4835 (comment))

andersy005 · 2021-02-03T19:51:56Z

Also, the build step also has a -W flag which turns warnings into Errors and causes a non 0 exit status. This is probably because the read the docs config file for xarray has a fail_on_warning set to true

Thank you for the clarification....

andersy005 · 2021-03-07T02:33:15Z

@dcherian,

Can we add another level of organization to API reference in the sidebar: "Top-Level Functions", "Dataset" etc.?

It'd be nice to get the left sidebar to "pin" like the right one. Right now if you scroll enough ,it disappears

I have yet to figure this out. If someone knows how to do this (whether with or without custom HTML template), please let me know :)

Another minor comment: How about renaming "external resources" to "Tutorials & Videos"? Similarly "Related projects" to "Ecosystem"?

Done!

@keewis,

The only issue I have with the new theme is that due to the maximum line length we use some examples have horizontal scroll bars (unless the left side bar is hidden).

I will see if there's a remedy for this.

doc/conf.py

keewis · 2021-03-07T11:06:34Z

I will see if there's a remedy for this.

You could try to reduce the (quite big) margin on the left / right

andersy005 · 2021-03-08T04:19:51Z

It'd be nice to get the left sidebar to "pin" like the right one. Right now if you scroll enough ,it disappears

@dcherian, this is fixed. When you get a moment, take another look and let me know if I missed anything.

…/new-theme

andersy005 · 2021-03-09T02:40:26Z

The only issue I have with the new theme is that due to the maximum line length we use some examples have horizontal scroll bars (unless the left side bar is hidden).

@keewis, I fixed this issue.

@pydata/xarray, this PR is ready. Unless there's any additional issue that needs to be addressed before merging, feel free to merge this.

keewis

@keewis, I fixed this issue.

thanks, I can confirm this is fixed.

Looking at pydata-sphinx-theme and sphinx-book-theme, both seem to have a doc_path or path_to_docs context variable which allows specifying a custom path (I think we can merge this PR in its current state and fix this and any other issues in a new PR, though). Even if we get the edit-on-github feature to work I would keep the source link: it is quite useful for development (especially for reviewing and answering issues & discussions).

The reasoning for the current behavior of the edit-on-github feature was that people were opening PRs to be merged into stable, which would then be dropped on a release. We could avoid that by either always linking to master (but then we can't determine the line numbers; this is what we are doing with scanpydoc), or by always opening a PR which also adds the commit to master (using a bot?). Another option would be to restrict PRs into stable to maintainers, but I'm not sure if github supports that.

…/new-theme

andersy005 · 2021-03-11T22:42:14Z

doc/conf.py

+html_theme = "sphinx_book_theme"
+html_title = ""
+
+html_context = {
+    "github_user": "pydata",
+    "github_repo": "xarray",
+    "github_version": "master",
+    "doc_path": "doc",
+}

 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {"logo_only": True}
-
-# Add any paths that contain custom themes here, relative to this directory.
-# html_theme_path = []
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-# html_title = None
+html_theme_options = dict(
+    # analytics_id=''  this is configured in rtfd.io
+    # canonical_url="",
+    repository_url="https://github.com/pydata/xarray",
+    repository_branch="master",
+    path_to_docs="doc",
+    use_edit_page_button=True,


Looking at pydata-sphinx-theme and sphinx-book-theme, both seem to have a doc_path or path_to_docs context variable which allows specifying a custom path (I think we can merge this PR in its current state and fix this and any other issues in a new PR, though).
The reasoning for the current behavior of the edit-on-github feature was that people were opening PRs to be merged into stable, which would then be dropped on a release. We could avoid that by either always linking to master (but then we can't determine the line numbers; this is what we are doing with scanpydoc), or by always opening a PR which also adds the commit to master (using a bot?)

@keewis, unless I am misunderstanding how the existing edit on Github button works, I think these settings allow us to replicate the existing behavior i.e. For (1) regular pages, the button links to the document/file in the master branch. For (2) API pages, the button is disabled and the [source] link links to the lines of code in the master branch. Could you elaborate on when/how with the new changes, the edit on GitHub button will result in pointing people to the wrong branch?

the edit on github link will currently point to the same branch / tag / commit the docs were built for (regardless of the page).

The existing fix (always point to master) makes it impossible to accurately determine the line numbers for API pages. Since we might even have removed that function I'm starting to think that it might be easier to not redirect at all but rather make the fact that the PR does not point to master more visible.

Not sure what the best way to do so is, though. Maybe have a workflow post a comment if the branch is not the dev branch?

Thank you for the clarification!

Not sure what the best way to do so is, though. Maybe have a workflow post a comment if the branch is not the dev branch?

I presume it'd be okay to merge this PR and then address this in a separate PR in the near future?

…/new-theme

andersy005 · 2021-03-15T13:18:15Z

I plan to merge this later today (unless there's any objection and/or necessary changes)

shoyer · 2021-03-15T18:30:43Z

+1

…

On Mon, Mar 15, 2021 at 6:18 AM Anderson Banihirwe ***@***.***> wrote: I plan to merge this later today (unless there's any objection and/or necessary changes) — You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub <#4835 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJJFVX555NNH4KALUDP22TTDYCK3ANCNFSM4WMDZXNA> .

…/new-theme

andersy005 · 2021-03-15T23:20:24Z

Thank you @keewis, @dcherian, @shoyer!

…indow * upstream/master: Fix regression in decoding large standard calendar times (pydata#5050) Fix sticky sidebar responsiveness on small screens (pydata#5039) Flexible indexes refactoring notes (pydata#4979) add a install xarray step to the upstream-dev CI (pydata#5044) Adds Dataset.query() method, analogous to pandas DataFrame.query() (pydata#4984) run tests on python 3.9 (pydata#5040) Add date attribute to datetime accessor (pydata#4994) 📚 New theme & rearrangement of the docs (pydata#4835) upgrade ci-trigger to the most recent version (pydata#5037) GH5005 fix documentation on open_rasterio (pydata#5021) GHA for automatically canceling previous CI runs (pydata#5025) Implement GroupBy.__getitem__ (pydata#3691) conventions: decode unsigned integers to signed if _Unsigned=false (pydata#4966) Added support for numpy.bool_ (pydata#4986) Add additional str accessor methods for DataArray (pydata#4622)

…-tasks * upstream/master: Fix regression in decoding large standard calendar times (pydata#5050) Fix sticky sidebar responsiveness on small screens (pydata#5039) Flexible indexes refactoring notes (pydata#4979) add a install xarray step to the upstream-dev CI (pydata#5044) Adds Dataset.query() method, analogous to pandas DataFrame.query() (pydata#4984) run tests on python 3.9 (pydata#5040) Add date attribute to datetime accessor (pydata#4994) 📚 New theme & rearrangement of the docs (pydata#4835) upgrade ci-trigger to the most recent version (pydata#5037) GH5005 fix documentation on open_rasterio (pydata#5021) GHA for automatically canceling previous CI runs (pydata#5025) Implement GroupBy.__getitem__ (pydata#3691) conventions: decode unsigned integers to signed if _Unsigned=false (pydata#4966) Added support for numpy.bool_ (pydata#4986) Add additional str accessor methods for DataArray (pydata#4622) add polyval to polyfit see also (pydata#5020) mention map_blocks in the docstring of apply_ufunc (pydata#5011) Switch backend API to v2 (pydata#4989) WIP: add new backend api documentation (pydata#4810) pin netCDF4=1.5.3 in min-all-deps (pydata#4982)

New theme & rearrangement of the docs

90ae42a

andersy005 added the topic-documentation label Jan 21, 2021

[skip-ci] Skip CI builds

42e3c56

andersy005 added 4 commits January 20, 2021 21:48

[skip-ci] Fix spacing for proper table renderring

4c0b6a2

Set maxdepth to 2

ef4e498

[skip-ci] Skip CI builds

8cbf52c

[skip-ci] Add "edit this page" button

893d7e0

andersy005 marked this pull request as ready for review January 21, 2021 05:54

andersy005 added 2 commits January 21, 2021 12:24

Merge branch 'master' of github.com:pydata/xarray into docs/new-theme

84e34eb

[skip-ci] Skip CI builds

6cfe8a8

andersy005 added the needs review label Jan 24, 2021

andersy005 added 11 commits February 1, 2021 07:35

New theme & rearrangement of the docs

7df46e0

[skip-ci] Skip CI builds

4480b96

[skip-ci] Fix spacing for proper table renderring

cbb49c7

Set maxdepth to 2

84a813f

[skip-ci] Skip CI builds

a1ce627

[skip-ci] Add "edit this page" button

7e44550

[skip-ci] Skip CI builds

2d9e2a1

Merge branch 'docs/new-theme' of github.com:andersy005/xarray into do…

de8fe49

…cs/new-theme

Merge branch 'master' of github.com:pydata/xarray into docs/new-theme

8551a67

Add examples and ecosystem to main menu

d82de12

[skip-ci] Reset TOC maxdepth

35ebb7d

Fix heading inconsistencies

1c4dbc4

andersy005 removed the needs review label Mar 7, 2021

[skip-ci] Revert to original heading

266cd6c

andersy005 commented Mar 7, 2021

View reviewed changes

doc/conf.py Outdated Show resolved Hide resolved

andersy005 added 2 commits March 7, 2021 06:13

[skip-ci] Enable redirects via rediraffe ext

f506538

[skip-ci] Sticky left sidebar

b7fa2ef

andersy005 added 2 commits March 8, 2021 19:10

[skip-ci] Reduce left and right margins -> more screen estate

e56b443

[skip-ci] Merge branch 'master' of github.com:pydata/xarray into docs…

85a9dfb

…/new-theme

dcherian approved these changes Mar 9, 2021

View reviewed changes

keewis approved these changes Mar 9, 2021

View reviewed changes

[skip-ci] Merge branch 'master' of github.com:pydata/xarray into docs…

0d3e954

…/new-theme

andersy005 commented Mar 11, 2021

View reviewed changes

andersy005 added 3 commits March 12, 2021 07:10

[skip-ci] Merge branch 'master' of github.com:pydata/xarray into docs…

590ed90

…/new-theme

[skip-ci] Merge branch 'master' of github.com:pydata/xarray into docs…

44527fb

…/new-theme

[skip-ci] Merge branch 'master' of github.com:pydata/xarray into docs…

00cc772

…/new-theme

[skip-ci] Merge branch 'master' of github.com:pydata/xarray into docs…

5128bd7

…/new-theme

andersy005 changed the title ~~New theme & rearrangement of the docs~~ 📚 New theme & rearrangement of the docs Mar 15, 2021

andersy005 merged commit 76d6d75 into pydata:master Mar 15, 2021

andersy005 deleted the docs/new-theme branch March 15, 2021 23:20

keewis mentioned this pull request Mar 26, 2021

Adds wrapping to tables in docs for improved readability. #1729

Closed

4 tasks

weiji14 mentioned this pull request Apr 9, 2021

front facing docs page icesat2py/icepyx#110

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

📚 New theme & rearrangement of the docs #4835

📚 New theme & rearrangement of the docs #4835

andersy005 commented Jan 21, 2021 •

edited

Loading

andersy005 commented Jan 21, 2021

andersy005 commented Feb 3, 2021

keewis commented Feb 3, 2021 •

edited

Loading

DocOtak commented Feb 3, 2021

andersy005 commented Feb 3, 2021 •

edited

Loading

andersy005 commented Feb 3, 2021

andersy005 commented Mar 7, 2021

keewis commented Mar 7, 2021

andersy005 commented Mar 8, 2021

andersy005 commented Mar 9, 2021

keewis left a comment •

edited

Loading

andersy005 Mar 11, 2021

keewis Mar 12, 2021

andersy005 Mar 15, 2021

keewis Mar 15, 2021

andersy005 commented Mar 15, 2021

shoyer commented Mar 15, 2021 via email

andersy005 commented Mar 15, 2021

📚 New theme & rearrangement of the docs #4835

📚 New theme & rearrangement of the docs #4835

Conversation

andersy005 commented Jan 21, 2021 • edited Loading

andersy005 commented Jan 21, 2021

andersy005 commented Feb 3, 2021

keewis commented Feb 3, 2021 • edited Loading

DocOtak commented Feb 3, 2021

andersy005 commented Feb 3, 2021 • edited Loading

andersy005 commented Feb 3, 2021

andersy005 commented Mar 7, 2021

keewis commented Mar 7, 2021

andersy005 commented Mar 8, 2021

andersy005 commented Mar 9, 2021

keewis left a comment • edited Loading

Choose a reason for hiding this comment

andersy005 Mar 11, 2021

Choose a reason for hiding this comment

keewis Mar 12, 2021

Choose a reason for hiding this comment

andersy005 Mar 15, 2021

Choose a reason for hiding this comment

keewis Mar 15, 2021

Choose a reason for hiding this comment

andersy005 commented Mar 15, 2021

shoyer commented Mar 15, 2021 via email

andersy005 commented Mar 15, 2021

andersy005 commented Jan 21, 2021 •

edited

Loading

keewis commented Feb 3, 2021 •

edited

Loading

andersy005 commented Feb 3, 2021 •

edited

Loading

keewis left a comment •

edited

Loading