Merge branch 'feature/sphinx_4.5.0_support' into 'master'

Bump Sphinx, Breathe and theme version to latest

See merge request espressif/esp-docs!22

.gitlab-ci.yml

@@ -99,7 +99,7 @@ build_idf_docs_html:
     - .build_template
   variables:
     DOCS_DIR: $CI_PROJECT_DIR/esp-idf/docs
-    IDF_COMMIT_ID: 989cb70289af8
+    IDF_COMMIT_ID: 8b402280489d4e73
   script:
       # add gitlab ssh key
     - cit_add_ssh_key "${GITLAB_KEY_PEM}"
@@ -119,7 +119,7 @@ build_idf_docs_pdf:
     - .build_template
   variables:
     DOCS_DIR: $CI_PROJECT_DIR/esp-idf/docs
-    IDF_COMMIT_ID: 989cb70289af8
+    IDF_COMMIT_ID: 8b402280489d4e73
   script:
       # add gitlab ssh key
     - cit_add_ssh_key "${GITLAB_KEY_PEM}"

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = esp-docs
-version = 0.2.5
+version = 1.0.0
 author = Espressif
 author_email = [email protected]
 description = Documentation building package used at Espressif
@@ -20,25 +20,22 @@ package_dir =
 packages = find:
 python_requires = >=3.7
 install_requires =
-    markupsafe<2.0 # Locking version due to current version of sphinx breaking with latest version of Jinja
-    Jinja2>=2.3,<3.0 # Locking version due to current version of sphinx breaking with latest version of Jinja
-    docutils==0.16 # Locking version due to issues with rendering lists, https://github.com/readthedocs/sphinx_rtd_theme/issues/1115
+    docutils<0.18
     cairosvg==2.5.1 # required by sphinxcontrib-svg2pdfconverter[CairoSVG]
-    sphinx==2.3.1
-    breathe==4.14.1
-    sphinx-copybutton==0.3.0
+    sphinx==4.5.0
+    breathe==4.33.1
+    sphinx-copybutton==0.5.0
     sphinx-notfound-page
-    sphinxcontrib-blockdiag==2.0.0
-    sphinxcontrib-seqdiag==2.0.0
-    sphinxcontrib-actdiag==2.0.0
+    sphinxcontrib-blockdiag==3.0.0
+    sphinxcontrib-seqdiag==3.0.0
+    sphinxcontrib-actdiag==3.0.0
     sphinxcontrib-nwdiag==2.0.0
     sphinxcontrib-wavedrom>=3.0,<3.1
-    sphinxcontrib-svg2pdfconverter[CairoSVG]==1.1.0
+    sphinxcontrib-svg2pdfconverter[CairoSVG]==1.2.0
     nwdiag==2.0.0
     recommonmark
-    future>=0.16.0 # for gen_esp_err_to_name.py
     sphinx_selective_exclude==1.0.3
-    sphinx_idf_theme==0.4.5
+    sphinx_idf_theme==1.0.1
 
 [options.packages.find]
 where = src

src/esp_docs/_static/theme_overrides.css

@@ -54,3 +54,9 @@ a.internal + em::before {
 .tool-sha256 {
   word-break: break-all;
 }
+
+/* Fix extra space in nested toctrees */
+.toctree-wrapper ul li>* {
+  margin-top: 0px !important;
+  margin-bottom: 0px !important;
+}

src/esp_docs/check_docs.py

@@ -6,6 +6,7 @@
 
 SANITIZE_FILENAME_REGEX = re.compile('[^:]*/([^/:]*)(:.*)')
 SANITIZE_LINENUM_REGEX = re.compile('([^:]*)(:[0-9]+:)(.*)')
+SANITIZE_DUPLICATE_LINENUM_REGEX = re.compile(r'([^:]*)(:[0-9]+\.)(.*)')
 
 
 def sanitize_line(line):
@@ -15,10 +16,12 @@ def sanitize_line(line):
     filter:
         - only filename, no path at the beginning
         - no line numbers after the filename
+        - no line numbers from duplicate definitions
     """
 
     line = re.sub(SANITIZE_FILENAME_REGEX, r'\1\2', line)
     line = re.sub(SANITIZE_LINENUM_REGEX, r'\1:line:\3', line)
+    line = re.sub(SANITIZE_DUPLICATE_LINENUM_REGEX, r'\1:line.\3', line)
     return line
 
 

src/esp_docs/conf_docs.py

@@ -306,7 +306,7 @@ def setup_user(app, config):
 
 
 def setup(app):
-    app.add_stylesheet('theme_overrides.css')
+    app.add_css_file('theme_overrides.css')
 
     # config values that are pushed in by build_docs,py
     if 'idf_target' not in app.config:

src/esp_docs/esp_extensions/link_roles.py

@@ -150,7 +150,7 @@ def run(self, **kwargs):
                 (language, link_text) = text.split(':')
                 env = self.document.settings.env
                 docname = env.docname
-                doc_path = env.doc2path(docname, None, None)
+                doc_path = env.doc2path(docname)
                 return_path = '../' * doc_path.count('/')  # path back to the root from 'docname'
                 # then take off 2/3 more paths for language/release/targetname and build the new URL
                 if env.config.idf_target:

src/esp_docs/latex_templates/preamble.tex

@@ -18,8 +18,6 @@
 %%% Needed for displaying Chinese in English documentation
 \usepackage{xeCJK}
 
-\usepackage{footnotebackref} %%link at the footnote to go to the place of footnote in the text
-
 %% spacing between line
 \usepackage{setspace}
 \singlespacing