Skip to content

ENH: add show_toc_level config option to choose visible levels of toc #256

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 28, 2020
Merged

ENH: add show_toc_level config option to choose visible levels of toc #256

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6abd036
adding toc level chooser
choldgraf Sep 23, 2020
7119d04
Update docs/user_guide/configuring.rst
choldgraf Sep 26, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@
"github_url": "https://github.com/pandas-dev/pydata-sphinx-theme",
"twitter_url": "https://twitter.com/pandas_dev",
"use_edit_page_button": True,
"show_toc_level": 1,
}

html_context = {
Expand Down
19 changes: 19 additions & 0 deletions docs/user_guide/configuring.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,3 +150,22 @@ use the following configuration:
html_theme_options = {
"navigation_with_keys": False
}


Show more levels of the in-page TOC by default
==============================================

Normally only the 2nd-level headers of a page are show in the right
table of contents, and deeper levels are only shown when they are part
of an active section (when it is scrolled on screen).

You can show deeper levels by default by using the following configuration:

.. code-block:: python

html_theme_options = {
"show_toc_level": 2
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "2" here might be a bit confusing with the above "only the 2nd-level headers ..." ?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I wasn't quite sure what was the most intuitive thing to use here. The "2" could either refer to the level of the header in the document, OR it could refer to the level of the in-page TOC to the right. AKA the confusion is because the 2nd-level of the in-page TOC refers to the third level headers on the page. Do you have an intuition for which would be less-confusing for people?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think as config value, "2" is certainly fine here, in the meaning: "show 2 levels in the toc", which I think is the clearest definition (you don't need to know how to start counting the levels, include the main title as 1st level or not?)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, if there are multiple 1st level headers, it are actually those that are shown in the TOC. It's only the 2nd level headers that are shown if there is a single main title. So maybe it's better to speak about "only the 1st level headers (after the main title) of a page are shown"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I liked the language that you added, to make it clear that the configuration is for how many TOC levels are displayed (whether they begin with first-level headers or second-level headers, it'll remain consistent then)

}

All headings up to and including the level specified will now be shown
regardless of what is displayed on the page.
3 changes: 3 additions & 0 deletions pydata_sphinx_theme/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,9 @@ def get_edit_url():

context["get_edit_url"] = get_edit_url

# Ensure that the max TOC level is an integer
context["theme_show_toc_level"] = int(context.get("theme_show_toc_level", 1))


# -----------------------------------------------------------------------------

Expand Down
2 changes: 1 addition & 1 deletion pydata_sphinx_theme/docs-toc.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@
<li class="nav-item toc-entry toc-h{{ loop.depth + 1 }}">
<a href="{{ item.url }}" class="nav-link">{{ item.title }}</a>
{%- if item.children -%}
<ul class="nav section-nav flex-column">
<ul class="nav section-nav flex-column{% if (loop.depth + 1) <= theme_show_toc_level %} visible{% endif %}">
{{ loop(item.children) }}
</ul>
{%- endif %}
Expand Down
2 changes: 1 addition & 1 deletion ...ndex.689d8a1e63c34b0b2966dc009a5ecd08.css → ...ndex.73d71520a4ca3b99cfee5594769eaaae.css
View file
Open in desktop

Large diffs are not rendered by default.

0 ...e/static/js/index.0c807b2b8646875702ce.js → ...e/static/js/index.3da636dd464baa7582d2.js
View file
Open in desktop
File renamed without changes.
6 changes: 3 additions & 3 deletions pydata_sphinx_theme/static/webpack-macros.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,13 @@
{% endmacro %}

{% macro head_pre_bootstrap() %}
<link rel="stylesheet" href="{{ pathto('_static/css/index.689d8a1e63c34b0b2966dc009a5ecd08.css', 1) }}">
<link rel="stylesheet" href="{{ pathto('_static/css/index.73d71520a4ca3b99cfee5594769eaaae.css', 1) }}">
{% endmacro %}

{% macro head_js_preload() %}
<link rel="preload" as="script" href="{{ pathto('_static/js/index.0c807b2b8646875702ce.js', 1) }}">
<link rel="preload" as="script" href="{{ pathto('_static/js/index.3da636dd464baa7582d2.js', 1) }}">
{% endmacro %}

{% macro body_post() %}
<script src="{{ pathto('_static/js/index.0c807b2b8646875702ce.js', 1) }}"></script>
<script src="{{ pathto('_static/js/index.3da636dd464baa7582d2.js', 1) }}"></script>
{% endmacro %}
3 changes: 2 additions & 1 deletion pydata_sphinx_theme/theme.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,5 @@ google_analytics_id =
show_prev_next = True
search_bar_text = Search the docs ...
search_bar_position = sidebar
navigation_with_keys = True
navigation_with_keys = True
show_toc_level = 1
6 changes: 6 additions & 0 deletions src/scss/index.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -350,8 +350,14 @@ table.field-list {
.bd-toc .nav {
.nav {
display: none;

// So we can manually specify a level as visible in the config
&.visible {
display: block;
}
}


> .active > ul {
display: block;
}
Expand Down
9 changes: 9 additions & 0 deletions tests/sites/base/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,3 +8,12 @@ Index ``with code`` in title
page1
page2
section1/index

A header
--------

A sub-header
~~~~~~~~~~~~

A sub-sub-header
````````````````
12 changes: 12 additions & 0 deletions tests/test_build.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,15 @@ def test_build_book(file_regression, sphinx_build):
)

sphinx_build.clean()


def test_toc_visibility(file_regression, sphinx_build):
sphinx_build.copy()

# Test that setting TOC level visibility works as expected
sphinx_build.build(["-D", "html_theme_options.show_toc_level=2"])
index_html = sphinx_build.get("index.html")

# The 3rd level headers should be visible, but not the fourth-level
assert "visible" in index_html.select(".toc-h2 ul")[0].attrs["class"]
assert "visible" not in index_html.select(".toc-h3 ul")[0].attrs["class"]