chore: bump all sphinx dependencies and stop running examples (#388)

Signed-off-by: ThibaultFy <thibault.fouqueray@gmail.com>

.github/workflows/build.yml

@@ -51,12 +51,12 @@ jobs:
 
       - name: Install Pandoc
         run: |
-          sudo wget https://github.com/jgm/pandoc/releases/download/3.1.8/pandoc-3.1.8-1-amd64.deb
-          sudo dpkg -i pandoc-3.1.8-1-amd64.deb
+          sudo wget https://github.com/jgm/pandoc/releases/download/3.1.11.1/pandoc-3.1.11.1-1-amd64.deb
+          sudo dpkg -i pandoc-3.1.11.1-1-amd64.deb
 
       - name: Install requirements
         run: |
-          pip install -r requirements.txt
+          pip install -r docs/doc-requirements.txt
 
       - name: Sphinx make
         working-directory: ./docs

.gitignore

@@ -135,6 +135,7 @@ _build/
 # Misc build artefacts
 tmp/**
 
+docs/source/tmp/**
 docs/source/documentation/references/**
 docs/source/substrafl_doc/api
 

CHANGELOG.md

@@ -9,13 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.34.0]
 
+### Changed
+
+- Bump Sphinx to 7.2.6, and upgrade linked dependencies ([#388](https://github.com/Substra/substra-documentation/pull/388))
+- Examples are not executed when building the documentation ([#388](https://github.com/Substra/substra-documentation/pull/388))
+
 ### Added
 
 - Support on Python 3.11 ([#367](https://github.com/Substra/substra-documentation/pull/367))
 - Add doc about task output permissions ([#369](https://github.com/Substra/substra-documentation/pull/369))
 - Examples now install torch on CPU only if launched on docker or remote mode ([#375](https://github.com/Substra/substra-documentation/pull/375))
 
-### Removed 
+### Removed
 
 - Mentions to Orchestrator distributed mode ([#379](https://github.com/Substra/substra-documentation/pull/379))
 

docs/doc-requirements.txt

@@ -0,0 +1,16 @@
+recommonmark==0.6.0
+sphinx==7.2.6
+sphinx-markdown-tables==0.0.17
+sphinx-rtd-theme==2.0.0
+sphinx-autobuild==2024.2.4
+sphinx_click==5.1.0
+click==8.1
+texttable==1.7.0
+myst-parser==2.0.0
+docutils==0.20.1
+sphinx-fontawesome==0.0.6
+sphinx-copybutton==0.5.2
+pyyaml==6.0
+nbsphinx==0.9.3
+pandoc==2.3
+git-python==1.0.3

docs/environment.yml

@@ -7,4 +7,4 @@ dependencies:
   - pandoc=3.1
   - pip
   - pip:
-      - -r ../requirements.txt
+      - -r doc-requirements.txt

docs/source/conf.py

@@ -116,6 +116,7 @@ def __call__(self, directory):
 """
 
 nbsphinx_epilog = nbsphinx_prolog
+nbsphinx_execute = "never"
 
 
 # zip the assets directory found in the examples directory and place it in the current dir
@@ -249,6 +250,8 @@ def copy_source_files(src, dest):
         source_path = Path(imported_module.__file__).resolve().parents[1] / repo.doc_dir
         copy_source_files(source_path, repo.dest_doc_dir)
 
+myst_all_links_external = True
+
 
 # reformat links to a section in a markdown files (not supported by myst_parser)
 def reformat_md_section_links(file_path: Path):
@@ -350,6 +353,9 @@ def reformat_md_section_links(file_path: Path):
 nitpick_ignore = [
     ("py:class", "pydantic.main.BaseModel"),
     ("py:class", "BaseModel"),
+    ("py:class", "FieldInfo"),
+    ("py:class", "ConfigDict"),
+    ("py:class", "ComputedFieldInfo"),
     ("py:class", "torch.nn.modules.module.Module"),
     ("py:class", "torch.nn.modules.Module"),
     ("py:class", "torch.nn.modules.loss._Loss"),
@@ -378,6 +384,7 @@ def reformat_md_section_links(file_path: Path):
     ("py:attr", "dst_type"),
     ("py:attr", "dtype"),
     ("py:attr", "device"),
+    ("py:attr", "assign"),
     ("py:func", "register_module_forward_hook"),
     ("py:func", "register_module_forward_pre_hook"),
     ("py:func", "register_module_full_backward_hook"),

examples_requirements.txt

@@ -1,5 +1,6 @@
-ipython==8.12.0
+ipython==8.21.0
 nbformat==5.9.2
+tqdm>=4.66.2
 -r docs/source/examples/substra_core/diabetes_example/assets/requirements.txt
 -r docs/source/examples/substra_core/titanic_example/assets/requirements.txt
 -r docs/source/examples/substrafl/get_started/torch_fedavg_assets/requirements.txt

requirements.txt

@@ -1,2 +1,2 @@
--r docs/requirements.txt
+-r docs/docs-requirements.txt
 -r examples_requirements.txt