👌 IMPROVE: RHS TOC sticky when scrolling option

[DrDrij]

Fixes https://github.com/QuantEcon/quantecon-book-theme/issues/133

• [x] Add config option to make the in-page-TOC in the right column sticky (stays in view when scrolling)
• [x] Highlight respective TOC items when scrolling

The page TOC will now highlight as the user scrolls.

A config option is required to activate the sticky feature and highlighting functionality. This defaults to False where the page TOC is not sticky.

sphinx:
  config:
    html_theme_options:
      sticky_contents: true

https://user-images.githubusercontent.com/5886045/122872398-bf5a5480-d373-11eb-83df-e286ca4ba482.mov

[mmcky]

nice work @DrDrij -- it would be good to get the preview building with the updated RHS toc. Is that possible?

[codecov[bot]]

Codecov Report

Merging #144 (a75930f) into master (976718a) will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #144   +/-   ##
=======================================
  Coverage   71.12%   71.12%           
=======================================
  Files           2        2           
  Lines         239      239           
=======================================
  Hits          170      170           
  Misses         69       69           

Flag	Coverage Δ
pytests	71.12% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

:mega: We’re building smart automated test selection to slash your CI/CD build times. Learn more

[mmcky]

@DrDrij is the outstanding checkbox still in work?

[mmcky]

re: option name perhaps we need to specify rhs perhaps.

The main toc is persistent_toc: true

So perhaps we need to differentiate these toc objects a bit more clearly. Maybe LHS == TOC and RHS == CONTENTS

[mmcky]

@DrDrij what do you think re: comments / names?

[mmcky]

@DrDrij do you think you would have some time in the next two weeks to see if we can close this?

[DrDrij]

@mmcky Great idea. Changed the parameter to sticky_contents: true from sticky_toc: true. Shall I create a PR on the myst sites to add the parameter? programming, python, advanced, datascience, julia? I suppose we only need to add it if we want sticky as true (default false).

I think that covers it for this PR :)

[mmcky]

@DrDrij thanks for this. I am wondering if we should make this default: true so that we don't have to change config. We can then turn it off it isn't what we want. Then the preview here will also show this in action and we can ask @jstac what he thinks.

• [x] fix merge conflicts

[mmcky]

@AakashGfude would you have time to fix up this merge conflict?

[AakashGfude]

@mmcky have fixed merge conflicts. Had to add some changes to pre-commit-config.yaml and setup.py for the CI to run. Have added in this PR itself, if it's ready to merge. Else will create a new PR.

[mmcky]

@AakashGfude what is the difference between

sticky_toc = False
persistent_sidebar = False

[AakashGfude]

@AakashGfude what is the difference between

sticky_toc = False
persistent_sidebar = False

@mmcky persistent_sidebar is for left toc, which is for the whole project. sticky_toc is for right hand toc, concerning only the current page. More info about persistent_sidebar is in this PR: https://github.com/QuantEcon/quantecon-book-theme/pull/143

[mmcky]

@AakashGfude It would be great if we can change sticky_toc: true to sticky_contents: true

[AakashGfude]

@AakashGfude It would be great if we can change sticky_toc: true to sticky_contents: true

@mmcky true, contents do sound like contents of the page. I will change it.sticky_rhs_toc can also be one option

[mmcky]

I think sticky_contents will be fine.

[mmcky]

@AakashGfude can you please resolve these conflicts after #186 is merged.

[AakashGfude]

@mmcky this is ready to be reviewed and merged.

[mmcky]

@AakashGfude the latest netlify doesn't seem to show the "sticky" rhs toc?

[mmcky]

@AakashGfude let's revert 0acf72c and I will update the quantecon-book-theme branch on lecture-python-programming.

https://github.com/QuantEcon/lecture-python-programming.myst

[mmcky]

@AakashGfude I just pushed c8fd78a

[mmcky]

@AakashGfude once you get the tests and merge conflict sorted -- then please ping me for review. Thanks.

[mmcky]

@AakashGfude this looks sticky now 👍

What do you think? I suspect @jstac will prefer the non-sticky version but it is nice that our theme can support this option.

[mmcky]

@jstac this PR enables the RHS within page contents to stay visible in the margin

https://64546294cce6883938fb185c--hungry-lovelace-7d0512.netlify.app/python_by_example.html

Let me know your thoughts on this? I am in two minds - I like the clean view of it just being at the top (i.e. not sticky) but it can be handy to navigated within the page with it available all the time.

[AakashGfude]

Thanks @mmcky. This looks good now. Yes, I think by default we should keep it non-sticky. Good to have the option.