✨ NEW: sphinx sidebars functionality

.readthedocs.yml

@@ -7,7 +7,6 @@ python:
         path: .
         extra_requirements:
           - sphinx
-      - requirements: docs/requirements.txt
 
 sphinx:
   builder: html

docs/conf.py

@@ -20,6 +20,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
+    "ablog",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -58,6 +59,18 @@
 html_sourcelink_suffix = ""
 html_favicon = "_static/logo.png"
 
+html_sidebars = {
+    "reference/blog/*": [
+        "sidebar-search-bs.html",
+        "postcard.html",
+        "recentposts.html",
+        "tagcloud.html",
+        "categories.html",
+        "archives.html",
+        "sbt-sidebar-nav.html",
+        "sbt-sidebar-footer.html",
+    ]
+}
 # 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".
@@ -87,7 +100,15 @@
     # For testing
     # "home_page_in_toc": True,
     # "single_page": True,
-    # "extra_footer": "<a href='https://google.com'>Test</a>",
+    # "extra_footer": "<a href='https://google.com'>Test</a>",  # DEPRECATED KEY
     # "extra_navbar": "<a href='https://google.com'>Test</a>",
 }
 html_baseurl = "https://sphinx-book-theme.readthedocs.io/en/latest/"
+
+# -- ABlog config -------------------------------------------------
+blog_path = "reference/blog"
+blog_post_pattern = "reference/blog/*.md"
+blog_baseurl = "https://sphinx-book-theme.readthedocs.io"
+fontawesome_included = True
+post_auto_image = 1
+post_auto_excerpt = 2

docs/configure.md

@@ -117,6 +117,50 @@ html_theme_options = {
 ```
 
 
+## Control the left sidebar items
+
+You can control what kind of content goes underneath the logo and name of your website in the top left.
+
+To do so, use the `html_sidebars` variable in your `conf.py` file. This takes a dictionary of filename patterns as keys, and a list of sidebar elements as values. Any files that match a key will have the corresponding sidebar elements placed in that page's sidebar.
+
+For example, the following configuration would include *only the footer* on pages under the `posts/` folder:
+
+```python
+html_sidebars = {
+    "posts/*": ["sbt-sidebar-footer.html"]
+}
+```
+
+You can also use `**` to apply a set of sidebars to **all** pages of your book. For example:
+
+```python
+html_sidebars = {
+    "**": ["sbt-sidebar-nav.html", "sbt-sidebar-footer.html"]
+}
+```
+
+See the [Sphinx HTML sidebars documentation](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars) for more information.
+
+### Default sidebar elements
+
+By default, this theme comes with these three theme-specific sidebar elements enabled on all pages:
+
+- `sidebar-search-bs.html`: A bootstrap-based search bar (from the [PyData Sphinx Theme](https://pydata-sphinx-theme.readthedocs.io/))
+- `sbt-sidebar-nav.html`: A bootstrap-based navigation menu for your book.
+- `sbt-sidebar-footer`: A [configurable](custom-footer) snippet of HTML to add to the sidebar (by default it is placed at the bottom).
+
+(custom-footer)=
+## Customize the sidebar footer
+
+You may choose your own HTML to include in the footer of your sidebar (or set it to be empty). To do so, use the following configuration variable in `conf.py`:
+
+```python
+extra_sidebar = "<p>Your HTML</p>"
+```
+
+This text will be placed at the bottom of the sidebar by default.
+
+
 ## Add a header to your Table of Contents
 
 If you'd like to add a header above a section of TOC links, use `:caption: My header text`

docs/layout.md

@@ -226,7 +226,7 @@ but I'll stop here.
 
 You can control some elements of the navigation bar. Here are the main features:
 
-### Expand sections of your navbar
+### Expand sections of your sidebar
 
 You can keep certain sub-sections of pages to be permanently expanded in your
 left Table of Contents. To do so, add a list of any pages you wish to be expanded

docs/reference/blog.md

@@ -0,0 +1,3 @@
+# Reference for Blog
+
+This page will be replaced by ABlog. It's here to make sure it's in the TOC.

docs/reference/blog/post1.md

@@ -0,0 +1,7 @@
+---
+author: Jo the Jovyan
+date: 2020-01-01
+---
+# Post 1
+
+Some content

docs/reference/blog/post2.md

@@ -0,0 +1,8 @@
+---
+author: Jo the Jovyan
+date: 2020-02-01
+---
+
+# Post 2
+
+Some sample content.

docs/reference/index.md

@@ -11,4 +11,13 @@ chapterpage1
 chapterpage2
 chapterpage3
 notebookpage1
+blog
+```
+
+Here's a sample post list:
+
+```{postlist}
+:date: "%Y-%m-%d"
+:format: "{date} - {title}"
+:excerpts:
 ```

setup.py

@@ -32,7 +32,7 @@
         "docutils>=0.15",
         "sphinx",
         "click",
-        "pydata-sphinx-theme~=0.4.0",
+        "pydata-sphinx-theme~=0.4.1",
         "beautifulsoup4",
         'importlib-resources~=3.0.0; python_version < "3.7"',
     ],
@@ -51,6 +51,7 @@
             "plotly",
             "sphinxcontrib-bibtex",
             "sphinx-thebe",
+            "ablog~=0.10.11",
         ],
         "testing": [
             "myst_nb~=0.10.1",

sphinx_book_theme/__init__.py

@@ -391,6 +391,9 @@ def setup(app: Sphinx):
 
     app.add_directive("margin", Margin)
 
+    # Update templates for sidebar
+    app.config.templates_path.append(os.path.join(package_dir, "_templates"))
+
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,

sphinx_book_theme/_templates/sbt-sidebar-footer.html

@@ -0,0 +1,6 @@
+{% if theme_navbar_footer_text %}{% set theme_extra_navbar=theme_navbar_footer_text %}{% endif %} <!-- To handle the deprecated key -->
+{% if theme_extra_navbar %}
+<div class="navbar_extra_footer">
+  {{ theme_extra_navbar }}
+</div>
+{% endif %}

sphinx_book_theme/_templates/sbt-sidebar-nav.html

@@ -0,0 +1,3 @@
+<nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
+    {{ generate_nav_html(include_item_names=True, with_home_page=theme_home_page_in_toc) }}
+</nav>

sphinx_book_theme/sidebar.html

@@ -9,18 +9,7 @@ <h1 class="site-logo" id="site-title">{{ docstitle }}</h1>
 </a>
 </div>
 
-<form class="bd-search d-flex align-items-center" action="{{ pathto('search') }}" method="get">
-  <i class="icon fas fa-search"></i>
-  <input type="search" class="form-control" name="q" id="search-input" placeholder="{{ theme_search_bar_text }}" aria-label="{{ theme_search_bar_text }}" autocomplete="off" >
-</form>
 
-<nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
-  {{ generate_nav_html(include_item_names=True, with_home_page=theme_home_page_in_toc) }}
-</nav>
-
-{% if theme_navbar_footer_text %}{% set theme_extra_navbar=theme_navbar_footer_text %}{% endif %} <!-- To handle the deprecated key -->
-{% if theme_extra_navbar %}
-<div class="navbar_extra_footer">
-  {{ theme_extra_navbar }}
-</div>
-{% endif %}
+{%- for sidebartemplate in sidebars %}
+{%- include sidebartemplate %}
+{%- endfor %}

sphinx_book_theme/theme.conf

@@ -2,7 +2,8 @@
 [theme]
 inherit = pydata_sphinx_theme
 pygments_style = tango
-stylesheet = sphinx-book-theme.c73dba93dc14e2148248cba6cd058605.css
+sidebars = sidebar-search-bs.html, sbt-sidebar-nav.html, sbt-sidebar-footer.html
+stylesheet = sphinx-book-theme.96fda1f60fab4d240516a951d4305d3a.css
 
 [options]
 single_page = False

src/jinja/theme.conf

@@ -0,0 +1,22 @@
+# Note: this should only be changed in src/jinja/theme.conf.j2
+[theme]
+inherit = pydata_sphinx_theme
+pygments_style = tango
+sidebars = sidebar-search-bs.html, sbt-sidebar-nav.html, sbt-sidebar-footer.html
+stylesheet = sphinx-book-theme.c73dba93dc14e2148248cba6cd058605.css
+
+[options]
+single_page = False
+expand_toc_sections = []
+path_to_docs =
+repository_url =
+repository_branch =
+launch_buttons = {}
+home_page_in_toc = False
+expand_sections = []
+navbar_footer_text =
+extra_navbar = Theme by the <a href="https://ebp.jupyterbook.org">Executable Book Project</a>
+extra_footer =
+use_issues_button = False
+use_repository_button = False
+theme_dev_mode = False

src/jinja/theme.conf.j2

@@ -2,6 +2,7 @@
 [theme]
 inherit = pydata_sphinx_theme
 pygments_style = tango
+sidebars = sidebar-search-bs.html, sbt-sidebar-nav.html, sbt-sidebar-footer.html
 stylesheet = {{ "src/scss/sphinx-book-theme.scss" | compiled_name }}
 
 [options]

src/scss/_main.scss

@@ -1049,3 +1049,45 @@ nav.bd-links {
 .prev-next-bottom {
     height: 3em;
 }
+
+/*********************************************
+* ABlog Custom CSS *
+*********************************************/
+ul.ablog-archive {
+    padding-left: 0px;
+}
+
+/* In-page post lists */
+ul.postlist {
+    padding-left: 0;
+
+    > li > p:first-child {
+        font-size: 1.5em;
+    }
+
+    li {
+        + li {
+            margin-top: 2em;
+        }
+
+        > p > a {
+            font-style: normal;
+            font-size: 1.3em;
+        }
+    }
+}
+
+// Sidebar rules specifically for ABlog
+div.bd-sidebar {
+    h2 {
+        font-size: 1.5em;
+    }
+    h3 {
+        font-size: 1.4em;
+    }
+
+    > ul {
+        list-style: none;
+        padding-left: 0;
+    }
+}