From 212dca159bc4c9a28941a7ec4e571f93e0f977c6 Mon Sep 17 00:00:00 2001 From: Kshitij Sobti Date: Thu, 6 Apr 2023 00:57:41 +0530 Subject: [PATCH] chore: Switch from edx-sphinx-theme to sphinx-book-theme The edx-sphinx theme is being deprecated, and replaced with sphinx-book-theme. This removes references to the deprecated theme and replaces them with the new standard theme for the platform. See https://github.com/openedx/edx-sphinx-theme/issues/184 --- CHANGELOG.rst | 3 +++ docs/conf.py | 50 ++++++++++++++++++++++++++++++++++---------- requirements/doc.in | 2 +- requirements/doc.txt | 26 ++++++++++++++++++----- 4 files changed, 64 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index c475659..c592ccd 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -14,6 +14,9 @@ Change Log Unreleased -------------------- +* Switch from ``edx-sphinx-theme`` to ``sphinx-book-theme`` since the former is + deprecated + [1.7.0] ------- diff --git a/docs/conf.py b/docs/conf.py index 8acc07c..f2f4c33 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -18,12 +18,11 @@ import os import re import sys +from datetime import datetime from subprocess import check_call -import edx_theme from django import setup as django_setup from django.conf import settings -from django.utils import six def get_version(*file_paths): @@ -65,7 +64,6 @@ def get_version(*file_paths): # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'edx_theme', 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', @@ -96,8 +94,8 @@ def get_version(*file_paths): # General information about the project. project = 'edx-rbac' -copyright = edx_theme.COPYRIGHT # pylint: disable=redefined-builtin -author = edx_theme.AUTHOR +copyright = f'{datetime.now().year}, Axim Collaborative, Inc' # pylint: disable=redefined-builtin +author = 'Axim Collaborative, Inc' project_title = 'edx-rbac' documentation_title = f"{project_title}" @@ -168,16 +166,46 @@ def get_version(*file_paths): # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'edx_theme' +html_theme = 'sphinx_book_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. # -# html_theme_options = {} +html_theme_options = { + "repository_url": "https://github.com/openedx/edx-rbac", + "repository_branch": "master", + "path_to_docs": "docs/", + "home_page_in_toc": True, + "use_repository_button": True, + "use_issues_button": True, + "use_edit_page_button": True, + # Please don't change unless you know what you're doing. + "extra_footer": """ + + Creative Commons License + +
+ These works by + Axim Collaborative, Inc + are licensed under a + Creative Commons Attribution-ShareAlike 4.0 International License. + """ +} # Add any paths that contain custom themes here, relative to this directory. -html_theme_path = [edx_theme.get_html_theme_path()] +# html_theme_path = [] # The name for this set of Sphinx documents. # " v documentation" by default. @@ -191,13 +219,13 @@ def get_version(*file_paths): # The name of an image file (relative to this directory) to place at the top # of the sidebar. # -# html_logo = None +html_logo = "https://logos.openedx.org/open-edx-logo-color.png" # The name of an image file (relative to this directory) to use as a favicon of # the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. # -# html_favicon = None +html_favicon = "https://logos.openedx.org/open-edx-favicon.ico" # 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, @@ -501,5 +529,5 @@ def on_init(app): # pylint: disable=unused-argument def setup(app): """Sphinx extension: run sphinx-apidoc.""" - event = 'builder-inited' if six.PY3 else b'builder-inited' + event = 'builder-inited' app.connect(event, on_init) diff --git a/requirements/doc.in b/requirements/doc.in index 24ed717..ebcceed 100644 --- a/requirements/doc.in +++ b/requirements/doc.in @@ -3,6 +3,6 @@ -r test.txt # Core and testing dependencies for this package doc8 # reStructuredText style checker -edx_sphinx_theme # edX theme for Sphinx output +sphinx-book-theme # Common theme for all Open edX projects readme_renderer # Validates README.rst for usage on PyPI Sphinx # Documentation builder diff --git a/requirements/doc.txt b/requirements/doc.txt index 702ac14..afcc404 100644 --- a/requirements/doc.txt +++ b/requirements/doc.txt @@ -4,6 +4,8 @@ # # make upgrade # +accessible-pygments==0.0.4 + # via pydata-sphinx-theme alabaster==0.7.13 # via sphinx asgiref==3.6.0 @@ -11,7 +13,11 @@ asgiref==3.6.0 # -r requirements/test.txt # django babel==2.12.1 - # via sphinx + # via + # pydata-sphinx-theme + # sphinx +beautifulsoup4==4.12.2 + # via pydata-sphinx-theme bleach==6.0.0 # via readme-renderer certifi==2022.12.7 @@ -75,6 +81,7 @@ doc8==1.1.1 docutils==0.19 # via # doc8 + # pydata-sphinx-theme # readme-renderer # restructuredtext-lint # sphinx @@ -92,8 +99,6 @@ edx-opaque-keys==2.3.0 # via # -r requirements/test.txt # edx-drf-extensions -edx-sphinx-theme==3.1.0 - # via -r requirements/doc.in exceptiongroup==1.1.1 # via # -r requirements/test.txt @@ -130,6 +135,7 @@ newrelic==8.8.0 packaging==23.1 # via # -r requirements/test.txt + # pydata-sphinx-theme # pytest # sphinx pbr==5.11.1 @@ -152,9 +158,13 @@ pycryptodomex==3.17 # via # -r requirements/test.txt # pyjwkest +pydata-sphinx-theme==0.13.3 + # via sphinx-book-theme pygments==2.15.1 # via + # accessible-pygments # doc8 + # pydata-sphinx-theme # readme-renderer # sphinx pyjwkest==1.4.2 @@ -220,16 +230,20 @@ six==1.16.0 # -r requirements/test.txt # bleach # edx-drf-extensions - # edx-sphinx-theme # pyjwkest # python-dateutil snowballstemmer==2.2.0 # via sphinx +soupsieve==2.4.1 + # via beautifulsoup4 sphinx==5.3.0 # via # -c requirements/common_constraints.txt # -r requirements/doc.in - # edx-sphinx-theme + # pydata-sphinx-theme + # sphinx-book-theme +sphinx-book-theme==1.0.1 + # via -r requirements/doc.in sphinxcontrib-applehelp==1.0.4 # via sphinx sphinxcontrib-devhelp==1.0.2 @@ -263,6 +277,8 @@ tomli==2.0.1 # coverage # doc8 # pytest +typing-extensions==4.5.0 + # via pydata-sphinx-theme urllib3==1.26.15 # via # -r requirements/test.txt