Skip to content

Commit

Permalink
Sync conf.py with Plone Sphinx Theme options
Browse files Browse the repository at this point in the history
  • Loading branch information
@stevepiercy
stevepiercy committed Nov 9, 2024
1 parent eb1b13f commit 580cacc
Showing 1 changed file with 143 additions and 88 deletions.
231 changes: 143 additions & 88 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,12 @@

project = "Plone Documentation"
copyright = "Plone Foundation"
author = "the Plone community"
author = "Plone community"
trademark_name = "Plone"
now = datetime.now()
year = str(now.year)
copyright = year


# 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 All @@ -43,24 +45,25 @@
# or your custom ones.
extensions = [
"myst_parser",
"notfound.extension",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary", # plone.api
"sphinx.ext.doctest", # plone.api
"sphinx.ext.graphviz",
"sphinx.ext.ifconfig",
"sphinx.ext.intersphinx",
"sphinx.ext.todo",
"sphinx.ext.viewcode", # plone.api
"sphinx_copybutton",
"sphinx_design",
"sphinx_examples",
"sphinx_reredirects",
"sphinx_sitemap",
"sphinxcontrib.httpdomain", # plone.restapi
"sphinxcontrib.httpexample", # plone.restapi
"sphinxcontrib.mermaid",
"sphinxcontrib.video",
"sphinxext.opengraph",
"sphinx.ext.viewcode", # plone.api
"sphinx.ext.autosummary", # plone.api
"sphinx.ext.graphviz",
"sphinxcontrib.mermaid",
"notfound.extension",
]

# If true, the Docutils Smart Quotes transform, originally based on SmartyPants
Expand All @@ -70,10 +73,6 @@
# hyphenated words to be marked as misspelled by spellchecker.
smartquotes = False

# The name of the Pygments (syntax highlighting) style to use.
# pygments_style = "sphinx.pygments_styles.PyramidStyle"
pygments_style = "sphinx"

# Options for the linkcheck builder
# Ignore localhost
linkcheck_ignore = [
Expand All @@ -99,14 +98,17 @@
r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",
r"https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-version-10-0", # volto
# Ignore unreliable sites
r"https://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi", # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects".
r"https://chromewebstore.google.com/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd", # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects".
r"https://stackoverflow.com", # volto and documentation # TODO retest with latest Sphinx.
# r"https://chromewebstore.google.com/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi", # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects".
# r"https://chromewebstore.google.com/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd", # TODO retest with latest Sphinx when upgrading theme. chromewebstore recently changed its URL and has "too many redirects".
# r"https://stackoverflow.com", # volto and documentation # TODO retest with latest Sphinx.
r"https://web.archive.org/", # volto
r"https://www.youtube.com/playlist", # volto, TODO remove after installing sphinxcontrib.youtube
r"https://www.upc.edu/en", # TODO remove after their certificate is fixed
# r"https://www.youtube.com/playlist", # volto, TODO remove after installing sphinxcontrib.youtube
r"http://z3c.pt", # fluke where Sphinx interprets this as a URL
]
linkcheck_allowed_redirects = { # TODO: Confirm usage of linkcheck_allowed_redirects
# All HTTP redirections from the source URI to the canonical URI will be treated as "working".
r"https://chrome\.google\.com/webstore/detail/.*": r"https://consent\.google\.com/.*",
}
linkcheck_anchors = True
linkcheck_timeout = 5
linkcheck_retries = 1
Expand Down Expand Up @@ -157,17 +159,131 @@
"toc.not_readable", # Suppress `WARNING: toctree contains reference to nonexisting document 'news*'`
]

html_js_files = ["patch_scrollToActive.js", "search_shortcut.js"]

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

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = "plone_sphinx_theme"
html_logo = "_static/logo.svg"
html_favicon = "_static/favicon.ico"
html_theme_options = {
"article_header_start": ["toggle-primary-sidebar"],
# "extra_navbar": """
# <p class="ploneorglink">
# <a href="https://plone.org">
# <img src="/_static/logo.svg" alt="plone.org" /> plone.org</a>
# </p>""",
"extra_footer": """<p>The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see <a href="https://plone.org/foundation/logo">https://plone.org/foundation/logo</a>. All other trademarks are owned by their respective owners.</p>
<p>Pull request previews by <a href="https://readthedocs.org/">Read the Docs</a>.</p>""",
# "navbar_center": ["chapter-title.html"],
"footer_end": ["version.html"],
"icon_links": [
{
"name": "GitHub",
"url": "https://github.com/plone/documentation",
"icon": "fa-brands fa-square-github",
"type": "fontawesome",
"attributes": {
"target": "_blank",
"rel": "noopener me",
"class": "nav-link custom-fancy-css"
}
},
{
"name": "Mastodon",
"url": "https://plone.social/@plone",
"icon": "fa-brands fa-mastodon",
"type": "fontawesome",
"attributes": {
"target": "_blank",
"rel": "noopener me",
"class": "nav-link custom-fancy-css"
}
},
{
"name": "X (formerly Twitter)",
"url": "https://x.com/plone",
"icon": "fa-brands fa-square-x-twitter",
"type": "fontawesome",
"attributes": {
"target": "_blank",
"rel": "noopener me",
"class": "nav-link custom-fancy-css"
}
},
],
"logo": {
"text": "Plone Sphinx Theme",
},
"navigation_with_keys": True,
"path_to_docs": "docs",
"repository_branch": "main",
"repository_url": "https://github.com/plone/documentation",
"search_bar_text": "Search",
"switcher": {
"json_url": "/_static/switcher.json",
"version_match": version,
},
"use_edit_page_button": True,
"use_issues_button": True,
"use_repository_button": True,
}
# suggest edit link
# remark: {{ file_name }} is mandatory in "edit_page_url_template"
html_context = {
"edit_page_url_template": "https://6.docs.plone.org/contributing/index.html?{{ file_name }}#making-contributions-on-github",
}

# Announce that we have an opensearch plugin
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_use_opensearch
html_use_opensearch = "https://6.docs.plone.org"

# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
html_title = "%(project)s v%(release)s" % {"project": project, "release": release}

# If false, no index is generated.
html_use_index = True

html_css_files = ["custom.css", ("print.css", {"media": "print"})]
html_js_files = [
"patch_scrollToActive.js",
"search_shortcut.js"
]

html_extra_path = [
"robots.txt",
]

# 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".
html_static_path = [
"volto/_static",
"_static", # Last path wins. See https://github.com/plone/documentation/pull/1442
]


# -- Options for autodoc ----------------------------------------------------

# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
# Automatically extract typehints when specified and place them in
# descriptions of the relevant function/method.
# autodoc_typehints = "description"

# Don't show class signature with the class' name.
autodoc_class_signature = "separated"


# -- Options for sphinx_sitemap to html -----------------------------

# Used by sphinx_sitemap to generate a sitemap
html_baseurl = "https://6.docs.plone.org/"
# https://sphinx-sitemap.readthedocs.io/en/latest/advanced-configuration.html#customizing-the-url-scheme
sitemap_url_scheme = "{link}"
sitemap_filename = "sitemap-custom.xml"

# -- Options for myST markdown conversion to html -----------------------------

# For more information see:
Expand All @@ -192,8 +308,6 @@
"fawrench": '<span class="fa fa-wrench" style="font-size: 1.6em;"></span>',
}

mermaid_version = "10.9.1"

# -- Intersphinx configuration ----------------------------------

# This extension can generate automatic links to the documentation of objects
Expand Down Expand Up @@ -224,6 +338,10 @@
graphviz_output_format = "svg"


# -- Mermaid configuration ----------------------------------
# mermaid_version = "10.9.1"


# -- OpenGraph configuration ----------------------------------

ogp_site_url = "https://6.docs.plone.org/"
Expand All @@ -236,6 +354,11 @@
]


# -- sphinx.ext.todo -----------------------
# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos
todo_include_todos = True


# -- sphinx-notfound-page configuration ----------------------------------

notfound_urls_prefix = ""
Expand All @@ -253,68 +376,6 @@
}


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

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = "sphinx_book_theme"

html_logo = "_static/logo.svg"
html_favicon = "_static/favicon.ico"

html_css_files = ["custom.css", ("print.css", {"media": "print"})]

# See http://sphinx-doc.org/ext/todo.html#confval-todo_include_todos
todo_include_todos = True

# Announce that we have an opensearch plugin
# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_use_opensearch
html_use_opensearch = "https://6.docs.plone.org"

html_sidebars = {
"**": [
"sidebar-logo.html",
"search-field.html",
"sbt-sidebar-nav.html",
]
}

html_theme_options = {
"path_to_docs": "docs",
"repository_url": "https://github.com/plone/documentation",
"repository_branch": "main",
"use_repository_button": True,
"use_issues_button": True,
"use_edit_page_button": True,
"search_bar_text": "Search",
"switcher": {
"json_url": "/_static/switcher.json",
"version_match": version,
},
"extra_navbar": """
<p class="ploneorglink">
<a href="https://plone.org">
<img src="/_static/logo.svg" alt="plone.org" /> plone.org</a>
</p>""",
"extra_footer": """<p>The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see <a href="https://plone.org/foundation/logo">https://plone.org/foundation/logo</a>. All other trademarks are owned by their respective owners.</p>
<p><a href="https://www.netlify.com">
<img src="https://www.netlify.com/img/global/badges/netlify-color-bg.svg" alt="Deploys by Netlify" />
</a></p>""",
}

# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
html_title = "%(project)s v%(release)s" % {"project": project, "release": release}

# If false, no index is generated.
html_use_index = True

# Used by sphinx_sitemap to generate a sitemap
html_baseurl = "https://6.docs.plone.org/"
# https://sphinx-sitemap.readthedocs.io/en/latest/advanced-configuration.html#customizing-the-url-scheme
sitemap_url_scheme = "{link}"

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

# Output file base name for HTML help builder.
Expand All @@ -339,14 +400,7 @@
# the title page.
latex_logo = "_static/logo_2x.png"


# suggest edit link
# remark: {{ file_name }} is mandatory in "edit_page_url_template"
html_context = {
"edit_page_url_template": "https://6.docs.plone.org/contributing/index.html?{{ file_name }}#making-contributions-on-github",
}


# -- Configuration for source_replacements extension -----------------------
# An extension that allows replacements for code blocks that
# are not supported in `rst_epilog` or other substitutions.
# https://stackoverflow.com/a/56328457/2214933
Expand All @@ -366,6 +420,7 @@ def source_replace(app, docname, source):
}


# Finally, configure app attributes.
def setup(app):
app.add_config_value("source_replacements", {}, True)
app.connect("source-read", source_replace)
Expand Down

0 comments on commit 580cacc

Please sign in to comment.