diff --git a/docs/_templates/navbar-version.html b/docs/_templates/navbar-version.html new file mode 100644 index 000000000..bbba17b2a --- /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 f701a99f5..cef57da51 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 f25de0f41..174768898 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 affb04f11..1d3248471 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 000000000..7fe6cd79f --- /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 000000000..7e7b76c2c --- /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 000000000..467becbb2 --- /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 000000000..96e981f97 --- /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 3ccb6fbaa..000000000 --- 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 40e36323e..5472985ec 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 4ec293e7a..9cf8be2d2 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