Adding configuration page and a few options (#57)

Author: choldgraf

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".

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/<your-org>/<your-repo>",
+     "twitter_url": "https://twitter.com/<your-handle>",
+   }
+
+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": [
+         {"name": "link-one-name", "url": "https://<link-one>"},
+         {"name": "link-two-name", "url": "https://<link-two>"}
+     ]
+   }
+
+
+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
+   }

pandas_sphinx_theme/docs-navbar.html

@@ -19,17 +19,26 @@
         <a class="nav-link" href="{{ main_nav_item.url }}">{{ main_nav_item.title }}</a>
     </li>
     {% endfor %}
-  </ul>
-  <ul class="navbar-nav ml-auto">
-    <li class="nav-item">
-      <a class="nav-link" href="https://github.com/pandas-dev/pandas" target="_blank" rel="noopener">
-        <span><i class="fab fa-github-alt" style="color:#333;font-size:1rem;line-height:1.25"></i></span>
-      </a>
-    </li>
+    {% for external_link in theme_external_links %}
     <li class="nav-item">
-      <a class="nav-link" href="https://twitter.com/pandas_dev" target="_blank" rel="noopener">
-        <span><i class="fab fa-twitter" style="color:#55acee;font-size:1rem;line-height:1.25"></i></span>
-      </a>
+        <a class="nav-link nav-external" href="{{ external_link.url }}">{{ external_link.name }}<i class="fas fa-external-link-alt"></i></a>
     </li>
+    {% endfor %}
+  </ul>
+  <ul class="navbar-nav ml-auto">
+    {% if theme_github_url | length > 2 %}
+      <li class="nav-item">
+        <a class="nav-link" href="{{ theme_github_url }}" target="_blank" rel="noopener">
+          <span><i class="fab fa-github-square"></i></span>
+        </a>
+      </li>
+    {% endif %}
+    {% if theme_twitter_url | length > 2 %}
+      <li class="nav-item">
+        <a class="nav-link" href="{{ theme_twitter_url }}" target="_blank" rel="noopener">
+          <span><i class="fab fa-twitter-square"></i></span>
+        </a>
+      </li>
+    {% endif %}
   </ul>
 </div>

pandas_sphinx_theme/docs-toc.html

@@ -13,4 +13,4 @@
         </li>
     {% endfor %}
     </ul>
-</nav>
+</nav>

pandas_sphinx_theme/layout.html

@@ -13,7 +13,9 @@
 
 {%- block css %}
     <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
-{{- css() }}
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/all.min.css" integrity="sha384-KA6wR/X5RY4zFAHpv/CnoG2UW1uogYfdnP67Uv7eULvTveboZJg0qUpmJZb5VqzN" crossorigin="anonymous">
+
+    {{- css() }}
     <link href="{{ pathto('_static/css/custom.css', 1) }}" rel="stylesheet">
 {%- endblock %}
 
@@ -58,9 +60,11 @@
               <div>
                 {% block body %} {% endblock %}
               </div>
+              {% if theme_show_prev_next %}
               <div class='prev-next-bottom'>
                 {{ prev_next(prev, next) }}
               </div>
+              {% endif %}
           </main>
 
       </div>

pandas_sphinx_theme/static/css/custom.css

@@ -248,6 +248,11 @@ body {
     border-style: none;
 }
 
+#navbar-main-elements li.nav-item i {
+  font-size: 0.7rem;
+  padding-left: 2px;
+  vertical-align: middle;
+}
 
 /* Collapsing of the TOC sidebar while scrolling */
 
@@ -288,4 +293,21 @@ div.prev-next-bottom a.right-next {
 
 div.prev-next-bottom a.right-next:after {
   content: " >>"
-}
+}
+
+/* Social media buttons */
+
+i.fab {
+  vertical-align: middle;
+  font-style: normal;
+  font-size: 1.5rem;
+  line-height:1.25;
+}
+
+i.fa-github-square:before {
+  color:#333;
+}
+
+i.fa-twitter-square:before {
+  color: #55acee
+}

pandas_sphinx_theme/theme.conf

@@ -5,4 +5,8 @@ pygments_style = tango
 
 [options]
 sidebarwidth = 270
-sidebar_includehidden = True
+sidebar_includehidden = True
+external_links = []
+github_url = ''
+twitter_url = ''
+show_prev_next = True