From 9acd8a1a5be02d099ac4dcf6a4284abc87976764 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Sat, 27 Mar 2021 14:13:12 -0700 Subject: [PATCH 01/17] Making navbar modular --- docs/_templates/navbar-version.html | 1 + docs/conf.py | 12 +- docs/user_guide/configuring.rst | 108 ++++++++++++++++-- pydata_sphinx_theme/__init__.py | 5 + .../_templates/navbar-logo.html | 19 +++ .../_templates/navbar-menu-buttons.html | 3 + .../_templates/navbar-menu-nav.html | 8 ++ .../_templates/sidebar-ethical-ads.html | 9 ++ .../_templates/sidebar-search-bs.html | 3 - pydata_sphinx_theme/docs-navbar.html | 56 +++------ pydata_sphinx_theme/theme.conf | 4 +- 11 files changed, 171 insertions(+), 57 deletions(-) create mode 100644 docs/_templates/navbar-version.html create mode 100644 pydata_sphinx_theme/_templates/navbar-logo.html create mode 100644 pydata_sphinx_theme/_templates/navbar-menu-buttons.html create mode 100644 pydata_sphinx_theme/_templates/navbar-menu-nav.html create mode 100644 pydata_sphinx_theme/_templates/sidebar-ethical-ads.html delete mode 100644 pydata_sphinx_theme/_templates/sidebar-search-bs.html diff --git a/docs/_templates/navbar-version.html b/docs/_templates/navbar-version.html new file mode 100644 index 0000000000..bbba17b2a0 --- /dev/null +++ b/docs/_templates/navbar-version.html @@ -0,0 +1 @@ +v{{ version }} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index f701a99f50..cef57da513 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,9 +21,11 @@ copyright = "2019, PyData Community" author = "PyData Community" -# The full version, including alpha/beta/rc tags -release = "0.0.1dev0" +from pathlib import Path +for ii in Path("../pydata_sphinx_theme/__init__.py").read_text().split("\n"): + if ii.startswith("__version__"): + version = release = ii.split("= ")[-1].strip('"').replace("dev0", "") # -- General configuration --------------------------------------------------- @@ -50,7 +52,7 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] html_sidebars = { - "contributing": ["sidebar-search-bs.html", "custom-template.html"], + "contributing": ["search-field.html", "custom-template.html"], "changelog": [], } @@ -77,9 +79,11 @@ ], "use_edit_page_button": True, "show_toc_level": 1, - # "navbar_align": "right", # For testing that the navbar items align properly + # "navbar_align": "left", # [left, content, right] For testing that the navbar items align properly + "navbar_left": ["navbar-logo.html", "navbar-version.html"], } + html_context = { "github_user": "pandas-dev", "github_repo": "pydata-sphinx-theme", diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index f25de0f412..1747688983 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -129,7 +129,7 @@ Configure the sidebar ``pydata_sphinx_theme`` provides two new sidebar items by default: - ``sidebar-nav-bs.html`` - a bootstrap-friendly navigation section -- ``sidebar-search-bs.html`` - a bootstrap-friendly search bar +- ``search-field.html`` - a bootstrap-friendly search bar By default, this theme's sidebar has these two elements in it. If you'd like to override this behavior and control the sidebar on a per-page basis, use the @@ -186,18 +186,34 @@ and you do not need to specify it if you wish to use the default. Configure the search bar position ================================= -To modify the position of the search bar, change the following variable in -your configuration file ``conf.py``. Possible options are 'navbar' and 'sidebar'. +To modify the position of the search bar, add the ``search-field.html`` +template to your **sidebar**, or to one of the **navbar** positions, depending +on where you want it to be placed. -By default the search bar is positioned in the sidebar since this is more -suitable for large navigation bars. +For example, if you'd like the search field to be in your side-bar, add it to +the sidebar templates like so: .. code:: python - html_theme_options = { - "search_bar_position": "navbar" + html_sidebars = { + "**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"] } +If instead you'd like to put the search bar in the top-right navbar, use the +following configuration: + +.. code:: python + + html_theme_options = { + "navbar_menu": ["navbar-menu-nav.html", "navbar-menu-buttons.html", "search-field.html"] + } + + +.. note:: + + By default the search bar is positioned in the sidebar since this is more + suitable for large navigation bars. + Configure the search bar text ============================= @@ -289,6 +305,65 @@ use this pattern: For information about configuring the sidebar's contents, see :ref:`configure-sidebar`. +Configure the navbar items +========================== + +You can choose which items show up in your navbar, as well as the order +in which they appear. + +Each menu item is a *template* in Sphinx, and you may +add any template you wish to your navbar menu via configuring ``conf.py``. +There are two navbar sections, corresponding to the following configuration +values: + +.. code-block:: python + + html_theme_options = { + ... + "navbar_left": ["list", "of", "templates"] # Populates the left navbar + "navbar_menu": ["list", "of", "templates"] # Populates the rest of the navbar + } + +By default, the following configuration is used: + +.. code-block:: python + + html_theme_options = { + ... + "navbar_left": ["navbar-logo.html"], + "navbar_menu": ["navbar-menu-nav.html", "navbar-menu-search.html", "navbar-menu-buttons.html"], + ... + } + +If you'd like to add your own custom template to this list, you +could do this with the following steps: + +1. Create an HTML file in a folder called ``_templates``. For example, if + you wanted to display the version of your documentation using a Jinja + template, you could create a file: ``_templates/version.html`` and put the + following in it: + + .. code-block:: html + + + {{ version }} + +1. Now add the file to your menu items. For example: + + .. code-block:: python + + html_theme_options = { + ... + "navbar_left": ["version.html", "menu-logo.html"], + ... + } + +.. note:: + + Generally speaking, navbar menu items will be **right-aligned**. However, the + ``navbar-menu-nav.html`` template any anything that comes before it will + be **left-aligned**. + Configure navbar menu item alignment ==================================== @@ -323,3 +398,22 @@ If you'd like these items to snap to the right of the page, use this configurati "navbar_align": "right" ... } + + +Adding ethical advertisements to your sidebar in ReadTheDocs +============================================================ + +If you're hosting your documentation on ReadTheDocs, you should consider +adding an explicit placement for their **ethical advertisements**. These are +non-tracking advertisements from ethical companies, and they help ReadTheDocs +sustain themselves and their free service. + +Ethical advertisements are added to your sidebar by default. To ensure they are +there if you manually update your sidebar, ensure that the ``sidebar-ethical-ads.html`` +template is added to your list. For example: + +.. code:: python + + html_sidebars = { + "**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"] + } \ No newline at end of file diff --git a/pydata_sphinx_theme/__init__.py b/pydata_sphinx_theme/__init__.py index affb04f113..1d3248471a 100644 --- a/pydata_sphinx_theme/__init__.py +++ b/pydata_sphinx_theme/__init__.py @@ -306,6 +306,11 @@ def 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)) + # Make sure the navbar menu items are a list + for section in ["theme_navbar_left", "theme_navbar_menu"]: + if isinstance(context[section], str): + context[section] = [ii.strip() for ii in context[section].split(",")] + # ----------------------------------------------------------------------------- diff --git a/pydata_sphinx_theme/_templates/navbar-logo.html b/pydata_sphinx_theme/_templates/navbar-logo.html new file mode 100644 index 0000000000..7fe6cd79fd --- /dev/null +++ b/pydata_sphinx_theme/_templates/navbar-logo.html @@ -0,0 +1,19 @@ +{% if logo %} +{% if not theme_logo_link %} + + + +{% elif theme_logo_link[:4] == 'http' %} + + + +{% else %} + + + +{% endif %} +{% else %} + +

{{ project }}

+ +{% endif %} \ No newline at end of file diff --git a/pydata_sphinx_theme/_templates/navbar-menu-buttons.html b/pydata_sphinx_theme/_templates/navbar-menu-buttons.html new file mode 100644 index 0000000000..7e7b76c2c0 --- /dev/null +++ b/pydata_sphinx_theme/_templates/navbar-menu-buttons.html @@ -0,0 +1,3 @@ +{%- block icon_links -%} +{%- include "icon-links.html" with context -%} +{%- endblock %} \ No newline at end of file diff --git a/pydata_sphinx_theme/_templates/navbar-menu-nav.html b/pydata_sphinx_theme/_templates/navbar-menu-nav.html new file mode 100644 index 0000000000..467becbb20 --- /dev/null +++ b/pydata_sphinx_theme/_templates/navbar-menu-nav.html @@ -0,0 +1,8 @@ + \ No newline at end of file diff --git a/pydata_sphinx_theme/_templates/sidebar-ethical-ads.html b/pydata_sphinx_theme/_templates/sidebar-ethical-ads.html new file mode 100644 index 0000000000..96e981f972 --- /dev/null +++ b/pydata_sphinx_theme/_templates/sidebar-ethical-ads.html @@ -0,0 +1,9 @@ +{% if READTHEDOCS %} +
+{% endif %} diff --git a/pydata_sphinx_theme/_templates/sidebar-search-bs.html b/pydata_sphinx_theme/_templates/sidebar-search-bs.html deleted file mode 100644 index 3ccb6fbaae..0000000000 --- a/pydata_sphinx_theme/_templates/sidebar-search-bs.html +++ /dev/null @@ -1,3 +0,0 @@ -{% if theme_search_bar_position == "sidebar" %} - {%- include "search-field.html" %} -{% endif %} \ No newline at end of file diff --git a/pydata_sphinx_theme/docs-navbar.html b/pydata_sphinx_theme/docs-navbar.html index 40e36323e8..5472985ec1 100644 --- a/pydata_sphinx_theme/docs-navbar.html +++ b/pydata_sphinx_theme/docs-navbar.html @@ -1,47 +1,19 @@
+ - {% if logo %} - {% if not theme_logo_link %} - - - - {% elif theme_logo_link[:4] == 'http' %} - - - - {% else %} - - - - {% endif %} - {% else %} - -

{{ project }}

- - {% endif %} + - - - {% set navbar_class, navbar_align = navbar_align_class() %} - + {% set navbar_class, navbar_align = navbar_align_class() %} +
diff --git a/pydata_sphinx_theme/theme.conf b/pydata_sphinx_theme/theme.conf index 4ec293e7a1..9cf8be2d2a 100644 --- a/pydata_sphinx_theme/theme.conf +++ b/pydata_sphinx_theme/theme.conf @@ -1,7 +1,7 @@ [theme] inherit = basic pygments_style = tango -sidebars = sidebar-search-bs.html, sidebar-nav-bs.html +sidebars = search-field.html, sidebar-nav-bs.html, sidebar-ethical-ads.html [options] sidebarwidth = 270 @@ -21,3 +21,5 @@ search_bar_position = sidebar navigation_with_keys = True show_toc_level = 1 navbar_align = content +navbar_left = navbar-logo.html +navbar_menu = navbar-menu-nav.html, navbar-menu-buttons.html From 74ab7c70bb24c80dce6451c3dfcf4b6bc095441f Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Wed, 31 Mar 2021 06:26:18 -0700 Subject: [PATCH 02/17] Update docs/user_guide/configuring.rst Co-authored-by: Joris Van den Bossche --- docs/user_guide/configuring.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index 1747688983..9601ef9f96 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -361,7 +361,7 @@ could do this with the following steps: .. note:: Generally speaking, navbar menu items will be **right-aligned**. However, the - ``navbar-menu-nav.html`` template any anything that comes before it will + ``navbar-menu-nav.html`` template and anything that comes before it will be **left-aligned**. Configure navbar menu item alignment @@ -416,4 +416,4 @@ template is added to your list. For example: html_sidebars = { "**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"] - } \ No newline at end of file + } From 2b8b8fc7e280789771ecb5ac1e2a158649bd2bb4 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Wed, 31 Mar 2021 06:26:25 -0700 Subject: [PATCH 03/17] Update docs/user_guide/configuring.rst Co-authored-by: Joris Van den Bossche --- docs/user_guide/configuring.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index 9601ef9f96..0c18b828b9 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -331,7 +331,7 @@ By default, the following configuration is used: html_theme_options = { ... "navbar_left": ["navbar-logo.html"], - "navbar_menu": ["navbar-menu-nav.html", "navbar-menu-search.html", "navbar-menu-buttons.html"], + "navbar_menu": ["navbar-menu-nav.html", "navbar-menu-buttons.html"], ... } From f25993dbc94e511afa5d453cff83fc1f1fa89ffe Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Thu, 1 Apr 2021 21:38:26 +0200 Subject: [PATCH 04/17] attempt to split in three --- pydata_sphinx_theme/__init__.py | 2 +- .../_templates/navbar-menu-nav.html | 2 +- pydata_sphinx_theme/docs-navbar.html | 18 +++++++++++++----- pydata_sphinx_theme/theme.conf | 3 ++- 4 files changed, 17 insertions(+), 8 deletions(-) diff --git a/pydata_sphinx_theme/__init__.py b/pydata_sphinx_theme/__init__.py index 1d3248471a..58b63c8362 100644 --- a/pydata_sphinx_theme/__init__.py +++ b/pydata_sphinx_theme/__init__.py @@ -307,7 +307,7 @@ def get_edit_url(): context["theme_show_toc_level"] = int(context.get("theme_show_toc_level", 1)) # Make sure the navbar menu items are a list - for section in ["theme_navbar_left", "theme_navbar_menu"]: + for section in ["theme_navbar_left", "theme_navbar_menu", "theme_navbar_right"]: if isinstance(context[section], str): context[section] = [ii.strip() for ii in context[section].split(",")] diff --git a/pydata_sphinx_theme/_templates/navbar-menu-nav.html b/pydata_sphinx_theme/_templates/navbar-menu-nav.html index 467becbb20..9bd06b98b7 100644 --- a/pydata_sphinx_theme/_templates/navbar-menu-nav.html +++ b/pydata_sphinx_theme/_templates/navbar-menu-nav.html @@ -1,4 +1,4 @@ -