Skip to content

chore: Switch from edx-sphinx-theme to sphinx-book-theme. #268

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

Merged
feanil merged 1 commit into from
Apr 21, 2023
Merged

chore: Switch from edx-sphinx-theme to sphinx-book-theme. #268

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
3 changes: 2 additions & 1 deletion CHANGELOG.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ Removed

Chore
+++++

* Switch from ``edx-sphinx-theme`` to ``sphinx-book-theme`` since the former is
deprecated
* Upgraded celery to latest 5.x version.

[2.2.0] - 2022-01-26
Expand Down
49 changes: 39 additions & 10 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,12 @@

import os
import sys
from datetime import datetime
from subprocess import check_call

import django

import edx_theme


sys.path.insert(0, os.path.join(os.path.abspath(os.path.dirname(__file__)), '..'))
os.environ['DJANGO_SETTINGS_MODULE'] = 'schema.settings'
Expand All @@ -44,7 +45,6 @@
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'edx_theme',
'sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
Expand Down Expand Up @@ -74,8 +74,8 @@

# General information about the project.
project = 'django-user-tasks'
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'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
Expand Down Expand Up @@ -144,16 +144,45 @@
# 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/django-user-tasks",
"repository_branch": "master",
"path_to_docs": "docs/",
"home_page_in_toc": True,
Copy link

@rgraber rgraber Mar 27, 2023

Choose a reason for hiding this comment

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

[question] Why are we leaving out logo_only ?

Copy link
Contributor Author

@xitij2000 xitij2000 Mar 28, 2023

Choose a reason for hiding this comment

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

Support for that seems to have been removed in this PR: https://github.com/executablebooks/sphinx-book-theme/pull/668/files#diff-56e5475bc04460ee05cd5ac9199ebbfa3e21f1bfa64ce5469cfb2f1890b41ccfL42

There is now a different mechanism for this as outlined here: executablebooks/sphinx-book-theme@b0e6b52#diff-ffa6fcfcf96f0b20b242a31c1346439658bb90a4e42e3c8fc8d0b1bc3d4b7277L59

The new default behaviour seems to match logo_only = True though.

"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": """
<a rel="license" href="https://creativecommons.org/licenses/by-sa/4.0/">
<img
alt="Creative Commons License"
style="border-width:0"
src="https://i.creativecommons.org/l/by-sa/4.0/80x15.png"/>
</a>
<br>
These works by
<a
xmlns:cc="https://creativecommons.org/ns#"
href="https://openedx.org"
property="cc:attributionName"
rel="cc:attributionURL"
>Axim Collaborative, Inc</a>
are licensed under a
<a
rel="license"
href="https://creativecommons.org/licenses/by-sa/4.0/"
>Creative Commons Attribution-ShareAlike 4.0 International License</a>.
"""
}
# 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.
# "<project> v<release> documentation" by default.
Expand All @@ -167,13 +196,13 @@
# 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,
Expand Down
2 changes: 1 addition & 1 deletion requirements/doc.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

django-rest-swagger # Generates a Swagger/Open API schema for the REST API
doc8 # reStructuredText style checker
edx-sphinx-theme # edX theme for Sphinx output
sphinx-book-theme # Common theme for all Open edX projects
rules # Needed to import user_tasks/rules.py for autodoc
Sphinx # Documentation builder
swagger2rst # Generates REST API documentation for Sphinx from a Swagger/Open API schema JSON file
Expand Down
28 changes: 22 additions & 6 deletions requirements/doc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@
#
# make upgrade
#
accessible-pygments==0.0.4
# via pydata-sphinx-theme
alabaster==0.7.13
# via sphinx
amqp==5.1.1
Expand All @@ -17,7 +19,11 @@ asgiref==3.6.0
attrs==23.1.0
# via jsonschema
babel==2.12.1
# via sphinx
# via
# pydata-sphinx-theme
# sphinx
beautifulsoup4==4.12.2
# via pydata-sphinx-theme
billiard==3.6.4.0
# via
# -r requirements/base.txt
Expand Down Expand Up @@ -93,13 +99,12 @@ doc8==1.1.1
docutils==0.19
# via
# doc8
# pydata-sphinx-theme
# readme-renderer
# restructuredtext-lint
# sphinx
drf-yasg==1.21.5
# via -r requirements/base.txt
edx-sphinx-theme==3.1.0
# via -r requirements/doc.in
idna==3.4
# via
# -r requirements/base.txt
Expand Down Expand Up @@ -159,6 +164,7 @@ packaging==23.1
# via
# -r requirements/base.txt
# drf-yasg
# pydata-sphinx-theme
# sphinx
pbr==5.11.1
# via stevedore
Expand All @@ -172,9 +178,13 @@ prompt-toolkit==3.0.38
# click-repl
pycparser==2.21
# via cffi
pydata-sphinx-theme==0.13.3
# via sphinx-book-theme
pygments==2.15.0
# via
# accessible-pygments
# doc8
# pydata-sphinx-theme
# readme-renderer
# rich
# sphinx
Expand Down Expand Up @@ -228,14 +238,18 @@ six==1.16.0
# -r requirements/base.txt
# bleach
# click-repl
# edx-sphinx-theme
snowballstemmer==2.2.0
# via sphinx
soupsieve==2.4
# via beautifulsoup4
sphinx==5.3.0
# via
# -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/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
Expand Down Expand Up @@ -263,7 +277,9 @@ tomli==2.0.1
twine==4.0.2
# via -r requirements/doc.in
typing-extensions==4.5.0
# via rich
# via
# pydata-sphinx-theme
# rich
uritemplate==4.1.1
# via
# -r requirements/base.txt
Expand Down