From d4bc259f4e05cbaa0295223ceaa342ea00fa2d39 Mon Sep 17 00:00:00 2001 From: gabalafou Date: Thu, 21 Dec 2023 16:30:33 -0700 Subject: [PATCH 1/3] landmark unique error due to in-page TOC --- docs/examples/in-page-toc.rst | 47 +++++++++++++++++++++++++++++++ docs/examples/index.rst | 1 + docs/user_guide/theme-elements.md | 4 --- 3 files changed, 48 insertions(+), 4 deletions(-) create mode 100644 docs/examples/in-page-toc.rst diff --git a/docs/examples/in-page-toc.rst b/docs/examples/in-page-toc.rst new file mode 100644 index 000000000..e9ae9a0ae --- /dev/null +++ b/docs/examples/in-page-toc.rst @@ -0,0 +1,47 @@ +:html_theme.sidebar_secondary.remove: true + +Test of in-page TOC with no right sidebar +========================================= + +This page tests that the local contents directive looks okay. + +We **do not recommend** using this directive on pages that use this theme +because PyData Theme provides an in-page table of contents in the right sidebar +by default. + +If you do choose to use an inline, in-page table of contents, we recommend that +you turn off the right sidebar (directions below). + +.. contents:: Page contents + :local: + + +Local contents directive +------------------------ + +What is a local contents directive? + +.. code-block:: rst + + .. contents:: Page contents + :local: + +You add this directive near the top of your ``.rst`` page to insert a table of +contents for that page, which is what this page does. + + +Turn off right sidebar for a single page +---------------------------------------- + +On the very top line of your ``.rst`` file, insert the following line: + +.. code-block:: rst + + :html_theme.sidebar_secondary.remove: true + +This will render the page without the right sidebar, also known as the secondary +sidebar, which contains the table of contents for that page. + +Be aware that if you remove the sidebar you may also remove the "Edit on ..." +and "Show source" links for that page, since by default those are configured for +the right sidebar. diff --git a/docs/examples/index.rst b/docs/examples/index.rst index a831b66df..02044c891 100644 --- a/docs/examples/index.rst +++ b/docs/examples/index.rst @@ -29,6 +29,7 @@ See the sections in the primary sidebar and below to explore. no-sidebar persistent-search-field + in-page-toc subpages/index mult_headers Link to an external site diff --git a/docs/user_guide/theme-elements.md b/docs/user_guide/theme-elements.md index b3b9137b8..464f5cd57 100644 --- a/docs/user_guide/theme-elements.md +++ b/docs/user_guide/theme-elements.md @@ -3,10 +3,6 @@ There are a few elements that are unique or particularly important to this theme. Some of these are triggered with configuration or Markdown syntax that is unique to the theme, and we cover them below. -```{contents} Page contents -:local: -``` - ## Mathematics Most Sphinx sites support math, but it is particularly important for scientific computing, so we illustrate support here as well. From 782ad2e4dad8b7abab27e4aeee8c95bb93c41db0 Mon Sep 17 00:00:00 2001 From: gabalafou Date: Fri, 22 Dec 2023 09:31:59 -0600 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Tania Allard --- docs/examples/in-page-toc.rst | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/examples/in-page-toc.rst b/docs/examples/in-page-toc.rst index e9ae9a0ae..149db6540 100644 --- a/docs/examples/in-page-toc.rst +++ b/docs/examples/in-page-toc.rst @@ -5,33 +5,32 @@ Test of in-page TOC with no right sidebar This page tests that the local contents directive looks okay. -We **do not recommend** using this directive on pages that use this theme +.. attention:: We **do not recommend** using this directive on pages that use this theme because PyData Theme provides an in-page table of contents in the right sidebar by default. If you do choose to use an inline, in-page table of contents, we recommend that -you turn off the right sidebar (directions below). +you turn off the right sidebar as follows. .. contents:: Page contents :local: -Local contents directive ------------------------- +Add a local table of contents (in-page) +--------------------------------------- -What is a local contents directive? +Add the local table of contents directive near the top of your ``.rst`` page: .. code-block:: rst .. contents:: Page contents :local: -You add this directive near the top of your ``.rst`` page to insert a table of -contents for that page, which is what this page does. +This directive will generate a table of contents for the section where this was added, as shown on this page. -Turn off right sidebar for a single page ----------------------------------------- +Turn off the right sidebar for a single page +-------------------------------------------- On the very top line of your ``.rst`` file, insert the following line: From a91c3eba697b572c2215d1b0bcd6c0b46c483980 Mon Sep 17 00:00:00 2001 From: gabalafou Date: Fri, 22 Dec 2023 15:44:13 -0700 Subject: [PATCH 3/3] fix lint? --- docs/examples/in-page-toc.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/examples/in-page-toc.rst b/docs/examples/in-page-toc.rst index 149db6540..06dd09e08 100644 --- a/docs/examples/in-page-toc.rst +++ b/docs/examples/in-page-toc.rst @@ -5,9 +5,11 @@ Test of in-page TOC with no right sidebar This page tests that the local contents directive looks okay. -.. attention:: We **do not recommend** using this directive on pages that use this theme -because PyData Theme provides an in-page table of contents in the right sidebar -by default. +.. attention:: + + We **do not recommend** using this directive on pages that use this theme + because PyData Theme provides an in-page table of contents in the right sidebar + by default. If you do choose to use an inline, in-page table of contents, we recommend that you turn off the right sidebar as follows. @@ -19,14 +21,15 @@ you turn off the right sidebar as follows. Add a local table of contents (in-page) --------------------------------------- -Add the local table of contents directive near the top of your ``.rst`` page: +Add the local table of contents directive near the top of your ``.rst`` page: .. code-block:: rst .. contents:: Page contents :local: -This directive will generate a table of contents for the section where this was added, as shown on this page. +This directive will generate a table of contents for the section where this was +added, as shown on this page. Turn off the right sidebar for a single page