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'