From 28c7018354eff8533e7052d6ff4158c24113443c Mon Sep 17 00:00:00 2001
From: Maxim Prokhorov <prokhorov.max@outlook.com>
Date: Tue, 11 Mar 2025 01:33:55 +0300
Subject: [PATCH] Docs - default to sphinx_rtd_theme
following examples and conf.py from sphinx_rtd_theme itself
---
doc/conf.py | 41 ++++++++++++++++++-----------------------
1 file changed, 18 insertions(+), 23 deletions(-)
diff --git a/doc/conf.py b/doc/conf.py
index 0eef82bc24..58df5eb922 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -34,7 +34,9 @@
extensions = [
'nbsphinx',
'sphinx.ext.mathjax',
+ 'sphinx_rtd_theme',
]
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -49,8 +51,9 @@
# General information about the project.
project = u'ESP8266 Arduino Core'
-copyright = u'2017, Ivan Grokhotkov'
+slug = re.sub(r'\W+', '-', project.lower())
author = u'Ivan Grokhotkov'
+copyright = author
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
@@ -71,7 +74,13 @@
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_venv', '_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = [
+ '_readthedocs',
+ '_venv',
+ '_build',
+ 'Thumbs.db',
+ '.DS_Store',
+]
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
@@ -85,7 +94,7 @@
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
-html_theme = 'default'
+html_theme = 'sphinx_rtd_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
@@ -98,12 +107,12 @@
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
-
# -- Options for HTMLHelp output ------------------------------------------
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'ESP8266ArduinoCoredoc'
+html_show_sourcelink = True
+# Output file base name for HTML help builder.
+htmlhelp_basename = slug
# -- Options for LaTeX output ---------------------------------------------
@@ -129,8 +138,7 @@
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
- (master_doc, 'ESP8266ArduinoCore.tex', u'ESP8266 Arduino Core Documentation',
- u'Ivan Grokhotkov', 'manual'),
+ (master_doc, f'{slug}.tex', f'{project} Documentation', author, 'manual'),
]
@@ -139,8 +147,7 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- (master_doc, 'esp8266arduinocore', u'ESP8266 Arduino Core Documentation',
- [author], 1)
+ (master_doc, slug, f'{project} Documentation', [author], 1)
]
@@ -150,19 +157,7 @@
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
- (master_doc, 'ESP8266ArduinoCore', u'ESP8266 Arduino Core Documentation',
- author, 'ESP8266ArduinoCore', 'One line description of project.',
- 'Miscellaneous'),
+ (master_doc, slug, f'{project} Documentation', author, slug, project, 'Miscellaneous'),
]
linkcheck_anchors_ignore = ["/#!"]
-
-# -- Use sphinx_rtd_theme for local builds --------------------------------
-# ref. https://github.com/snide/sphinx_rtd_theme#using-this-theme-locally-then-building-on-read-the-docs
-#
-# on_rtd is whether we are on readthedocs.org
-env_readthedocs = os.environ.get('READTHEDOCS', None)
-
-if not env_readthedocs: # only import and set the theme if we're building docs locally
- import sphinx_rtd_theme
- html_theme = 'sphinx_rtd_theme'