Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

UPDATE: Sphinx v4.0.0 #364

Merged
merged 16 commits into from
Sep 15, 2021
Merged

UPDATE: Sphinx v4.0.0 #364

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
bbdfe27
Update Sphinx to include v4
choldgraf Aug 3, 2021
6da8076
Fix logo for upgrade
choldgraf Aug 3, 2021
9e983da
Merge branch 'master' into sphinx-4
chrisjsewell Aug 6, 2021
59ab648
Tests use Sphinx 4
choldgraf Aug 6, 2021
9c07d6c
Merge branch 'master' into sphinx-4
mmcky Sep 2, 2021
215ddda
upgrade myst-nb to 0.13
mmcky Sep 2, 2021
7bdc1c5
Revert "upgrade myst-nb to 0.13"
mmcky Sep 2, 2021
4cab78d
Update MyST NB and click
choldgraf Sep 2, 2021
8b7f5b4
Update setup.py
choldgraf Sep 2, 2021
48b7556
Fixing import for Margin directive
choldgraf Sep 2, 2021
61392b9
remove default from myst-parser settings
mmcky Sep 2, 2021
ba3aa83
add in sphinx3 and sphinx4 fixture tracking and update CI
mmcky Sep 2, 2021
e188ee1
[pre-commit.ci] auto fixes from pre-commit.com hooks
pre-commit-ci[bot] Sep 2, 2021
797523b
Exclude docutils==0.17 for now
mmcky Sep 2, 2021
9b8f93f
Merge branch 'sphinx-4' of https://github.com/ExecutableBookProject/s…
mmcky Sep 2, 2021
f473b30
Merge branch 'master' into sphinx-4
mmcky Sep 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/workflows/tests.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,14 @@ jobs:
matrix:
os: [ubuntu-latest]
python-version: [3.6, 3.7, 3.8]
sphinx: [">=3,<4", ">=4,<5"]
include:
- os: windows-latest
python-version: 3.7
sphinx: ">=3,<4"
- os: macos-latest
python-version: 3.9
sphinx: ">=4,<5"
runs-on: ${{ matrix.os }}

steps:
Expand Down
1 change: 0 additions & 1 deletion docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,6 @@
# "linkify",
# "substitution",
]
myst_url_schemes = ("http", "https", "mailto")

# -- Options for HTML output -------------------------------------------------

Expand Down
17 changes: 9 additions & 8 deletions setup.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,13 +28,13 @@
license="BSD",
packages=find_packages(),
install_requires=[
"pyyaml",
"docutils>=0.15",
"sphinx>=2,<4",
"click",
"pydata-sphinx-theme~=0.6.0",
"beautifulsoup4>=4.6.1,<5",
"click~=7.1",
"docutils>=0.15,<0.17",
'importlib-resources>=3.0,<3.5; python_version < "3.7"',
"pydata-sphinx-theme~=0.6.0",
"pyyaml",
"sphinx>=3,<5",
],
extras_require={
"code_style": ["pre-commit~=2.7.0"],
Expand All @@ -44,10 +44,11 @@
"folium",
"numpy",
"matplotlib",
"myst-nb~=0.11.1",
"myst-nb~=0.13",
"nbclient",
"pandas",
"plotly",
"sphinx~=4.0", # Force Sphinx to be the latest version
"sphinx-design",
"sphinx-copybutton",
"sphinx-togglebutton>=0.2.1",
Expand All @@ -56,12 +57,12 @@
"sphinxext-opengraph",
],
"testing": [
"myst_nb~=0.11.1",
"sphinx_thebe",
"coverage",
"myst_nb~=0.13",
"pytest~=6.0.1",
"pytest-cov",
"pytest-regressions~=2.0.1",
"sphinx_thebe",
],
"live-dev": ["sphinx-autobuild", "web-compile~=0.2.1"],
},
Expand Down
4 changes: 2 additions & 2 deletions sphinx_book_theme/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
import importlib_resources as resources

from bs4 import BeautifulSoup as bs
from docutils.parsers.rst import directives
from docutils.parsers.rst.directives.body import Sidebar
from docutils import nodes
from sphinx.application import Sphinx
from sphinx.locale import get_translation
Expand Down Expand Up @@ -254,7 +254,7 @@ def _string_or_bool(var):
return var is None


class Margin(directives.body.Sidebar):
class Margin(Sidebar):
"""Goes in the margin to the right of the page."""

optional_arguments = 1
Expand Down
6 changes: 5 additions & 1 deletion sphinx_book_theme/_templates/sidebar-logo.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,11 @@
<div class="navbar-brand-box">
<a class="navbar-brand text-wrap" href="{{ pathto('index') }}">
{% if logo %}
<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="logo">
<!-- `logo` is deprecated in Sphinx 4.0, so remove this when we stop supporting 3 -->
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@choldgraf good find! Thanks.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh cool it looks like there are html_logo and latex_logo now

https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=logo#confval-html_logo

This is something we will need to manage in jupyter-book to issue a depcration notice for logo in jupyter-book/jupyter-book#1438

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we may not need to deprecate it if we are managing it under the hood though!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK -- if html or latex isn't specified use logo -- I see where you are going

{% set logo_url=logo %}
{% endif %}
{% if logo_url %}
<img src="{{ pathto('_static/' + logo_url, 1) }}" class="logo" alt="logo">
{% endif %}
{% if docstitle and not theme_logo_only %}
<h1 class="site-logo" id="site-title">{{ docstitle }}</h1>
Expand Down
12 changes: 10 additions & 2 deletions tests/test_build.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@

from bs4 import BeautifulSoup
import pytest
import sphinx
from sphinx.errors import ThemeError
from sphinx.testing.util import SphinxTestApp
from sphinx.testing.path import path as sphinx_path
Expand All @@ -17,6 +18,9 @@ class SphinxBuild:
def __init__(self, app: SphinxTestApp, src: Path):
self.app = app
self.src = src
self.software_versions = (
f".sphinx{sphinx.version_info[0]}" # software version tracking for fixtures
)

def build(self, assert_pass=True):
self.app.build()
Expand Down Expand Up @@ -85,7 +89,11 @@ def test_build_book(sphinx_build_factory, file_regression):
# Check a few components that should be true on each page
index_html = sphinx_build.html_tree("index.html")
sidebar = index_html.find_all(attrs={"class": "bd-sidebar"})[0]
file_regression.check(sidebar.prettify(), extension=".html", encoding="utf8")
file_regression.check(
sidebar.prettify(),
extension=f"{sphinx_build.software_versions}.html",
encoding="utf8",
)

# Edit button should not be on page
assert '<a class="edit-button"' not in str(index_html)
Expand All @@ -106,7 +114,7 @@ def test_build_book(sphinx_build_factory, file_regression):
file_regression.check(
page_toc.prettify(),
basename=page.with_suffix("").name,
extension=".html",
extension=f"{sphinx_build.software_versions}.html",
encoding="utf8",
)

Expand Down
0 tests/test_build/page-multipletitles.html → ...st_build/page-multipletitles.sphinx3.html
View file
Open in desktop
File renamed without changes.
35 changes: 35 additions & 0 deletions tests/test_build/page-multipletitles.sphinx4.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
<div class="d-none d-md-block col-md-2 bd-toc show">
<div class="tocsection onthispage pt-5 pb-3">
<i class="fas fa-list">
</i>
Contents
</div>
<nav aria-label="Page" id="bd-toc-nav">
<ul class="visible nav section-nav flex-column">
<li class="toc-h1 nav-item toc-entry">
<a class="reference internal nav-link" href="#">
4.1. A page with multiple top-level titles
</a>
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#a-sub-heading">
4.1.1. A sub-heading
</a>
</li>
</ul>
</li>
<li class="toc-h1 nav-item toc-entry">
<a class="reference internal nav-link" href="#another-top-level-title">
4.2. Another top-level title
</a>
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#another-sub-heading">
4.2.1. Another sub-heading
</a>
</li>
</ul>
</li>
</ul>
</nav>
</div>
0 tests/test_build/page-onetitle.html → tests/test_build/page-onetitle.sphinx3.html
View file
Open in desktop
File renamed without changes.
21 changes: 21 additions & 0 deletions tests/test_build/page-onetitle.sphinx4.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
<div class="d-none d-md-block col-md-2 bd-toc show">
<div class="tocsection onthispage pt-5 pb-3">
<i class="fas fa-list">
</i>
Contents
</div>
<nav aria-label="Page" id="bd-toc-nav">
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#here-s-a-sub-heading">
4.3.1. Here’s a sub-heading
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#here-s-another">
4.3.2. Here’s another
</a>
</li>
</ul>
</nav>
</div>
0 ...s/test_build/page-onetitlenoheadings.html → ...uild/page-onetitlenoheadings.sphinx3.html
View file
Open in desktop
File renamed without changes.
2 changes: 2 additions & 0 deletions tests/test_build/page-onetitlenoheadings.sphinx4.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<div class="d-none d-md-block col-md-2 bd-toc show">
</div>
0 tests/test_build/test_build_book.html → ...s/test_build/test_build_book.sphinx3.html
View file
Open in desktop
File renamed without changes.
112 changes: 112 additions & 0 deletions tests/test_build/test_build_book.sphinx4.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
<div class="col-12 col-md-3 bd-sidebar site-navigation show" id="site-navigation">
<div class="navbar-brand-box">
<a class="navbar-brand text-wrap" href="#">
<h1 class="site-logo" id="site-title">
Sphinx Book Theme documentation
</h1>
</a>
</div>
<form action="search.html" class="bd-search d-flex align-items-center" method="get">
<i class="icon fas fa-search">
</i>
<input aria-label="Search the docs ..." autocomplete="off" class="form-control" id="search-input" name="q" placeholder="Search the docs ..." type="search"/>
</form>
<nav aria-label="Main" class="bd-links" id="bd-docs-nav">
<div class="bd-toc-item active">
<p class="caption" role="heading">
<span class="caption-text">
My caption
</span>
</p>
<ul class="nav bd-sidenav">
<li class="toctree-l1">
<a class="reference internal" href="page1.html">
1. Page 1
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="page2.html">
2. Page 2
</a>
</li>
<li class="toctree-l1 has-children">
<a class="reference internal" href="section1/index.html">
3. Section 1 index
</a>
<input class="toctree-checkbox" id="toctree-checkbox-1" name="toctree-checkbox-1" type="checkbox">
<label for="toctree-checkbox-1">
<i class="fas fa-chevron-down">
</i>
</label>
<ul>
<li class="toctree-l2">
<a class="reference internal" href="section1/page1.html">
3.1. Section 1 page1
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="section1/ntbk.html">
3.2. A test notebook
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="section1/ntbkmd.html">
3.3. Section 1 page1
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="section1/ntbk_octave.html">
3.4. Octave
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="section1/ntbk_julia.html">
3.5. Julia
</a>
</li>
</ul>
</input>
</li>
<li class="toctree-l1 has-children">
<a class="reference internal" href="titles/index.html">
4. Testing titles and TOCtree
</a>
<input class="toctree-checkbox" id="toctree-checkbox-2" name="toctree-checkbox-2" type="checkbox"/>
<label for="toctree-checkbox-2">
<i class="fas fa-chevron-down">
</i>
</label>
<ul>
<li class="toctree-l2">
<a class="reference internal" href="titles/page-multipletitles.html">
4.1. A page with multiple top-level titles
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="titles/page-onetitle.html">
4.3. A page with one title and sub-headings
</a>
</li>
<li class="toctree-l2">
<a class="reference internal" href="titles/page-onetitlenoheadings.html">
4.4. A page with a title but no sub-headings
</a>
</li>
</ul>
</li>
<li class="toctree-l1">
<a class="reference external" href="https://google.com">
https://google.com
</a>
</li>
</ul>
</div>
</nav>
<!-- To handle the deprecated key -->
<div class="navbar_extra_footer">
Theme by the
<a href="https://ebp.jupyterbook.org">
Executable Book Project
</a>
</div>
</div>
4 changes: 2 additions & 2 deletions tox.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,11 @@ envlist = py37-sphinx3
[testenv]
usedevelop=true

[testenv:py{36,37,38}-sphinx{2,3}]
[testenv:py{36,37,38}-sphinx{3,4}]
extras = testing
deps =
sphinx2: sphinx>=2,<3
sphinx3: sphinx>=3,<4
sphinx4: sphinx>=4,<5
commands = pytest {posargs}

[testenv:py{36,37,38}-pre-commit]
Expand Down