From 82fa8e68562df4f707e6345d3fa42efdd85f76fe Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Wed, 20 Nov 2019 20:16:51 -0800 Subject: [PATCH 1/3] adding configuration page and a few options --- docs/conf.py | 11 ++++++ docs/user_guide/configuring.rst | 47 ++++++++++++++++++++++- pandas_sphinx_theme/docs-navbar.html | 29 +++++++++----- pandas_sphinx_theme/layout.html | 6 ++- pandas_sphinx_theme/static/css/custom.css | 26 ++++++++++++- pandas_sphinx_theme/theme.conf | 6 ++- 6 files changed, 111 insertions(+), 14 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 6ddb618f3..ebd94139f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -53,6 +53,17 @@ html_theme = 'pandas_sphinx_theme' html_logo = '_static/pandas.svg' +html_theme_options = { + "external_links": [ + { + 'url': "https://pandas.pydata.org/pandas-docs/stable/", + "name": "Pandas Docs" + } + ], + "github_url": "https://github.com/pandas-dev/pandas-sphinx-theme", + "twitter_url": "https://twitter.com/pandas_dev", +} + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index a432c733b..132eaed1e 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -2,4 +2,49 @@ Configuration ************* -TODO +There are a number of options for configuring your site's look and feel. +All configuration options are passed with the ``html_theme_options`` variable +in your ``conf.py`` file. This is a dictionary with ``key: val`` pairs that +you can configure in various ways. This page describes the options available to you. + +Configure social media buttons +============================== + +If you'd like social media buttons to show up to the right of your nav bar, use the +following configuration: + +.. code:: python + + html_theme_options: { + "github_url": "https://github.com//", + "twitter_url": "https://twitter.com/", + } + +Adding external links to your nav bar +===================================== + +You can add external links to your navigation bar. These will show up to the right +of your site's main links, and will have a small icon indicating that they point to +an external site. You can add external links to the nav bar like so: + +.. code:: python + + html_theme_options: { + "external_links": [ + "https://", + "https://" + ] + } + + +Hiding the previous and next buttons +==================================== + +By default, each page of your site will have "previous" and "next" buttons +at the bottom. You can hide these buttons with the following configuration: + +.. code:: python + + html_theme_options: { + "show_prev_next": False + } diff --git a/pandas_sphinx_theme/docs-navbar.html b/pandas_sphinx_theme/docs-navbar.html index 6754462b6..26a12c43a 100644 --- a/pandas_sphinx_theme/docs-navbar.html +++ b/pandas_sphinx_theme/docs-navbar.html @@ -19,17 +19,26 @@ {{ main_nav_item.title }} {% endfor %} - - +
    + {% if theme_github_url | length > 2 %} +
  • + + + +
    • + {% endif %} + {% if theme_twitter_url | length > 2 %} +
  • + + + +
    • + {% endif %}
diff --git a/pandas_sphinx_theme/layout.html b/pandas_sphinx_theme/layout.html index ab207a0a6..ce9886dea 100644 --- a/pandas_sphinx_theme/layout.html +++ b/pandas_sphinx_theme/layout.html @@ -13,7 +13,9 @@ {%- block css %} -{{- css() }} + + + {{- css() }} {%- endblock %} @@ -58,9 +60,11 @@
{% block body %} {% endblock %}
+ {% if theme_show_prev_next %}
{{ prev_next(prev, next) }}
+ {% endif %} diff --git a/pandas_sphinx_theme/static/css/custom.css b/pandas_sphinx_theme/static/css/custom.css index b1c8683d0..148b26c02 100644 --- a/pandas_sphinx_theme/static/css/custom.css +++ b/pandas_sphinx_theme/static/css/custom.css @@ -248,6 +248,13 @@ body { border-style: none; } +.nav-external:after { + font-family: 'FontAwesome'; + font-size: 0.7rem; + vertical-align: middle; + content: " \f08e"; +} + /* Collapsing of the TOC sidebar while scrolling */ @@ -288,4 +295,21 @@ div.prev-next-bottom a.right-next { div.prev-next-bottom a.right-next:after { content: " >>" -} \ No newline at end of file +} + +/* Social media buttons */ + +i.fab:before { + font-family: 'FontAwesome'; + vertical-align: middle; + font-style: normal; + font-size: 1.5rem; +} + +i.fa-github-square:before { + content: "\f092"; +} + +i.fa-twitter-square:before { + content: "\f081"; +} diff --git a/pandas_sphinx_theme/theme.conf b/pandas_sphinx_theme/theme.conf index 3708d4a64..e34ca1bcf 100644 --- a/pandas_sphinx_theme/theme.conf +++ b/pandas_sphinx_theme/theme.conf @@ -5,4 +5,8 @@ pygments_style = tango [options] sidebarwidth = 270 -sidebar_includehidden = True \ No newline at end of file +sidebar_includehidden = True +external_links = [] +github_url = '' +twitter_url = '' +show_prev_next = True From d865799f32623b2ed023094b78c0d3dab4499eef Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 25 Nov 2019 18:17:36 -0800 Subject: [PATCH 2/3] fontawesome 5 and minor fixes --- docs/user_guide/configuring.rst | 4 ++-- pandas_sphinx_theme/docs-navbar.html | 6 +++--- pandas_sphinx_theme/docs-toc.html | 2 +- pandas_sphinx_theme/layout.html | 2 +- pandas_sphinx_theme/static/css/custom.css | 14 ++++++-------- 5 files changed, 13 insertions(+), 15 deletions(-) diff --git a/docs/user_guide/configuring.rst b/docs/user_guide/configuring.rst index 132eaed1e..566fd7f9a 100644 --- a/docs/user_guide/configuring.rst +++ b/docs/user_guide/configuring.rst @@ -31,8 +31,8 @@ an external site. You can add external links to the nav bar like so: html_theme_options: { "external_links": [ - "https://", - "https://" + {"name": "link-one-name", "url": "https://"}, + {"name": "link-two-name", "url": "https://"} ] } diff --git a/pandas_sphinx_theme/docs-navbar.html b/pandas_sphinx_theme/docs-navbar.html index 26a12c43a..c779bd386 100644 --- a/pandas_sphinx_theme/docs-navbar.html +++ b/pandas_sphinx_theme/docs-navbar.html @@ -21,7 +21,7 @@ {% endfor %} {% for external_link in theme_external_links %}
  • - {{ external_link.name }} + {{ external_link.name }}
    • {% endfor %} @@ -29,14 +29,14 @@ {% if theme_github_url | length > 2 %}
  • - +
    • {% endif %} {% if theme_twitter_url | length > 2 %}
  • - +
    • {% endif %} diff --git a/pandas_sphinx_theme/docs-toc.html b/pandas_sphinx_theme/docs-toc.html index 9a3c3d628..a2f796916 100644 --- a/pandas_sphinx_theme/docs-toc.html +++ b/pandas_sphinx_theme/docs-toc.html @@ -3,7 +3,7 @@