New sidebar structure #138

javabster · 2022-11-30T20:27:20Z

fixes #72 , fixes #70

This PR restyles the sidebar and makes it configurable for users of the theme in the following way:

Previous Releases dropdown only visible if users set their html context to have a version_list.
Language dropdown only visible if users set their html context to have a translations_list.
Sidebar titles by default are set by the toctree list in users' index.rst. This PR also updates the qiskit_sphinx_theme README with a recommended list of sidebar headings
Users can also optionally add custom sidebar headings via the sidebar_headings variable in their conf.py. This is also now explained in the README

Other work in this PR:

Styles tidied up and made consistent
external links in sidebar (either from toctree or custom) have a 'opens new tab' icon added
removed unnecessary sidebar code leftover from previous pytorch theme

Tasks:

figure out how toc tree works to get dynamic page population
make sidebar contents configurable via conf.py
make sidebar headings expandable
refactor language dropdown
refactor previous releases section
make pretty ✨
update with main

* resolved merge conflicts * Made helpful buttons configurable * Added segment analytics and restyled thankyou msg

…into new-sidebar

HuangJunye

I will need a bit more time to review it thoroughly. The expandable sidebar is great and I also like the README instructions. The translations pages may need special care and we should add needed code to test that in the sample docs. The qiskit meta doc has this file to add the translations_list and translation_url.

HuangJunye · 2023-01-16T17:02:03Z

docs/conf.py

+    'repo_name': 'Example Repo',
+    'analytics_enabled': True,
+    'version_list': [0.1, 0.2, 0.3],
+    'sidebar_headings': [


Do you think this is a better approach than adding an additional toctree in indez.rst beyond the main one like how qiskit meta is doing?

the only way i could get the dropdowns to work with subpages is by specifying them here. If you just put it in the toctree in index.rst you don't get to customise what goes in the dropdown menu, it will just automatically populate it with the headings on the page and doesn't include sub pages

alternatively we could do something like the qiskit runtime docs with headings and full list of subpages, but then we don't get an expandable dropdown

qiskit_sphinx_theme/sidebar.html

javabster · 2023-01-17T09:07:48Z

The translations pages may need special care and we should add needed code to test that in the sample docs. The qiskit meta doc has this file to add the translations_list and translation_url.

yes i think some test code in the sample docs would be great! Should that go in your PR or should I try include it here?

HuangJunye · 2023-01-17T10:39:23Z

The translations pages may need special care and we should add needed code to test that in the sample docs. The qiskit meta doc has this file to add the translations_list and translation_url.

yes i think some test code in the sample docs would be great! Should that go in your PR or should I try include it here?

I think it would be better to include here so that we can test before merging this PR.

javabster · 2023-02-06T10:32:37Z

I copied over the languages functionality from qiskit/docs/versionutils.py, so we now have a language_utils.py extension in the docs subfolder that we can use to test out any work we do to the languages box (and it could be a nice template for others wanting to set up their own language funcitonality). If I remove the last setup line in conf.py I can see that the language dropdown disappears if the language dropdown component can't find the languages. And if we add that line back the language dropdown shows up and works as expected (currently the language links just redirect to 404s)

e.g. with languages enabled

e.g. with languages not enabled

HuangJunye

Overall LGTM. I left a few small comments. This is a major improvement for the theme. I am excited to see it get deployed to the docs sites!

HuangJunye · 2023-02-07T10:45:02Z

README.md

+
+The above toctree will render a sidebar that looks like the image below:
+
+<img width="348" alt="Screenshot 2022-11-30 at 4 36 26 PM" src="https://user-images.githubusercontent.com/23662430/204913247-761b8202-1bb2-4233-9451-f180b00b5a12.png">


The expendable sidebar feature is not shown in the screenshots, probably because the index.rst files are empty in the example. We should probably clean up the sample doc and make it more like a template and put in things placeholder content under each pages. For this PR though, can you do something like that locally and update these screenshots to show the expandable feature?

That screenshot is not meant to show any expandable items. By default there are no expandable headings unless they explicitly configure them in their setup.py. This screenshot is meant to show what is displayed when there is just a toctree defined and the screenshots later down show the same sidebar with the additional expandable headings once they're configured :)

qiskit_sphinx_theme/sidebar.html

HuangJunye · 2023-02-07T10:50:58Z

qiskit_sphinx_theme/sidebar.html

+        {% if version_list %}
+            <div class="sidebar-l1-expandable">Previous Releases</div>
+            <div class="sidebar-subheadings">
+                {% for version in version_list | sort(reverse=True) %}
+                <div class="sidebar-l2"><a href="/documentation/stable/{{ version }}/index.html">{{ version }}</a></div>
+                {% endfor %}
+            </div>
+        {% endif %}


Just nitpicking. Can you fix the indentation here?

HuangJunye · 2023-02-07T10:53:22Z

docs/conf.py

+            'subheadings': [
+                {
+                    'title': 'Custom Subtitle 1 (external link)',
+                    'url': 'https://google.com', # use external url


Can you change the external link to something else? Like https://qiskit.org/ or youtube.com/qiskit

javabster · 2023-02-07T12:03:56Z

Update: after discussion with @HuangJunye I'm going to refactor this PR to move the configuration aspect out of the conf.py into the index.rst. The plan now is for devs to create individual toctrees for each expandable section, and if they set expandable_sidebar=True in their conf.py it will make toctrees with a caption expandable.

This is similar to what Pytorch does:

javabster · 2023-02-09T11:53:02Z

Update: I've refactored this so that its now easier to implement the expandable sidebar using just the toctree in the index.rst rather than from the conf.py. The new workflow for devs is this:

if they don't want expandable sidebar items they can set the toctree how they want, with captions and sections, but everything will be shown in the sidebar. The formatting will look slightly different from the existing theme due to some design changes we made after consulting with Jules from the design team.
if they want to make the sidebar expandable they need to update their conf.py with a expandable_sidebar: True variable AND they need to structure their toctree in their index.rst into separate sections, where sections that include a :caption: directive will be made into expandable headings

I think this solution provides the best outcome visually with minimal changes needed to be made by the dev teams themselves.

See below examples of the same sidebar with and without expandable sidebars enabled:

HuangJunye

Overall it looks great. Thanks for working on this. I only have a few small comments for README.

README.md

HuangJunye · 2023-02-20T19:03:59Z

README.md

+2. Refactor the `toctree` in your `index.rst` to separate your pages into different sections. Sections that include a `:caption:` directive will be turned into expandable sidebar sections, with the caption forming the title of the dropdown. for example, to render the expandable sidebar shown above your `toctree` in your `index.rst` should look like this:
+    ```
+    .. toctree::
+    :maxdepth: 1


It's not necessary to specify maxdepth. The same applies to other lines.

Co-authored-by: Junye Huang <h.jun.ye@gmail.com>

This PR adds missing chevron svg file used in footer Previous/Next buttons (original image accidentally removed in #138 ). It also updates references from `chevron-right-orange` to `chevron-right-purple`, matching the fill colour used. Updated footer rendering: ![image](https://user-images.githubusercontent.com/25207344/228622405-0e8a0ac2-f1b2-44af-be2c-85ee4ac48d52.png) Fixes #189

This PR adds missing chevron svg file used in footer Previous/Next buttons (original image accidentally removed in Qiskit#138 ). It also updates references from `chevron-right-orange` to `chevron-right-purple`, matching the fill colour used. Updated footer rendering: ![image](https://user-images.githubusercontent.com/25207344/228622405-0e8a0ac2-f1b2-44af-be2c-85ee4ac48d52.png) Fixes Qiskit#189

) This PR adds missing chevron svg file used in footer Previous/Next buttons (original image accidentally removed in #138 ). It also updates references from `chevron-right-orange` to `chevron-right-purple`, matching the fill colour used. Updated footer rendering: ![image](https://user-images.githubusercontent.com/25207344/228622405-0e8a0ac2-f1b2-44af-be2c-85ee4ac48d52.png) Fixes #189 Co-authored-by: Karla Spuldaro <karla.spuldaro@ibm.com>

javabster and others added 14 commits October 6, 2022 16:24

First experiments with sidebar refactor

dee3a4c

Add segment analytics (Qiskit#74)

f002eea

* resolved merge conflicts * Made helpful buttons configurable * Added segment analytics and restyled thankyou msg

Started refeactring sidebar

9632728

Made more configurable

de15055

Some changes to sidebar and styles

de18682

Fixed sidebar dropdown issues

1efe719

Fixed language dropdown and styling

a40cdc5

Updated README and fixed style bug

c180a4f

Tidied up files

663d457

Tidied up code

f998824

Merge branch 'layout_refactor' into new-sidebar

da65827

Merge branch 'main' of https://github.com/Qiskit/qiskit_sphinx_theme …

674eff2

…into new-sidebar

Fixed some small merge issues and styles

0ecc6a5

Resolved merge conflicts

615ce51

javabster requested review from 1ucian0 and HuangJunye November 30, 2022 21:15

Updated README

23c6aab

HuangJunye self-assigned this Dec 2, 2022

Merge branch 'main' of https://github.com/Qiskit/qiskit_sphinx_theme …

737b24b

…into new-sidebar

HuangJunye reviewed Jan 16, 2023

View reviewed changes

Added dummy language extension

d406caf

Attempted to fix parallel warning

19652c6

HuangJunye suggested changes Feb 7, 2023

View reviewed changes

HuangJunye added this to the Qiskit Sphinx Theme v1.12.0 milestone Feb 7, 2023

Tidied up code

e1645b1

javabster added 3 commits February 9, 2023 12:38

Refactor sidebar logic

de0c88d

Fix toctree lint

4e3e81f

lint

ef80851

fix toctree

2f796f6

HuangJunye reviewed Feb 20, 2023

View reviewed changes

javabster and others added 2 commits February 20, 2023 21:37

Apply suggestions from code review

b10b49d

Co-authored-by: Junye Huang <h.jun.ye@gmail.com>

Updated README

622b38c

HuangJunye approved these changes Feb 21, 2023

View reviewed changes

HuangJunye merged commit fb2f874 into Qiskit:main Feb 21, 2023

This was referenced Feb 27, 2023

TOC entries links are bold #188

Closed

previous and next button chevron not showing #189

Closed

karlaspuldaro mentioned this pull request Mar 29, 2023

Add missing chevron on previous-next buttons #237

Merged

Eric-Arellano mentioned this pull request Mar 29, 2023

Add missing chevron on previous-next buttons (Cherry-pick of #237) #238

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

New sidebar structure #138

New sidebar structure #138

javabster commented Nov 30, 2022 •

edited

Loading

HuangJunye left a comment

HuangJunye Jan 16, 2023

javabster Jan 17, 2023

javabster Jan 17, 2023

javabster commented Jan 17, 2023

HuangJunye commented Jan 17, 2023

javabster commented Feb 6, 2023

HuangJunye left a comment

HuangJunye Feb 7, 2023

javabster Feb 7, 2023

HuangJunye Feb 7, 2023

HuangJunye Feb 7, 2023

javabster commented Feb 7, 2023

javabster commented Feb 9, 2023

HuangJunye left a comment

HuangJunye Feb 20, 2023


		The above toctree will render a sidebar that looks like the image below:

		<img width="348" alt="Screenshot 2022-11-30 at 4 36 26 PM" src="https://user-images.githubusercontent.com/23662430/204913247-761b8202-1bb2-4233-9451-f180b00b5a12.png">

New sidebar structure #138

New sidebar structure #138

Conversation

javabster commented Nov 30, 2022 • edited Loading

HuangJunye 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

javabster commented Jan 17, 2023

HuangJunye commented Jan 17, 2023

javabster commented Feb 6, 2023

HuangJunye 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

javabster commented Feb 7, 2023

javabster commented Feb 9, 2023

HuangJunye left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

javabster commented Nov 30, 2022 •

edited

Loading