From 9d568d7ca0873ca6c030793561039c5367de6e1f Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Tue, 3 May 2022 10:37:33 +0200 Subject: [PATCH] Clarify use-case and docs structure (#648) --- docs/index.rst | 17 ++++++++++++++--- docs/user_guide/index.rst | 10 ++++++++++ 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index e37b026c2..3173a017d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,11 +2,22 @@ The PyData Sphinx Theme ======================= -This is a simple, Bootstrap-based Sphinx theme from the PyData community. This -site is a guide for using the theme, and a demo for how it looks with various +A clean, Bootstrap-based Sphinx theme from the PyData community. +This theme is designed for more complex documentation that breaks into natural sub-sections. + +It puts all top-level pages in your ``toctree`` into the header navigation bar. +The sidebar will be populated with second-level pages when a top-level page is active. +This allows you to group your documentation into sub-sections without cluttering the sidebar. + +.. seealso:: + + If you are looking for a Sphinx theme that puts all of its sub-pages in the sidebar, the `Sphinx Book Theme `_ has a similar look and feel, and `Furo `_ is another excellent choice. + +This site is a guide for using the theme, and a demonstration for how it looks with various elements. -Other sites that are using this theme: +Sites that use this theme +========================= .. SORTED ALPHABETICALLY diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst index 49c6e0e06..02524547f 100644 --- a/docs/user_guide/index.rst +++ b/docs/user_guide/index.rst @@ -2,6 +2,16 @@ User Guide ========== +The user guide describes how to use and customize this theme. + +How the theme is structured +=========================== + +This theme converts all **top-level toctree items** into links in the header navigation bar. +The sidebar will have no navigation links until one of these top-level links is active (e.g., if you are on a sub-page of a top-level link). +Once one of the top-level links is active, the sidebar will be populated with a list of pages that are underneath the top-level page. + +For example, see the links in the sidebar for the other pages in this section. .. toctree:: :maxdepth: 2