Merge pull request #92 from Louis-Pujol/main

Examples folder outside of docs/
smarie · Mar 15, 2024 · b1125b7 · b1125b7
2 parents 8a16972 + f7577c2
commit b1125b7
Show file tree

Hide file tree

Showing 26 changed files with 17 additions and 12 deletions.
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -1,5 +1,9 @@
 # Changelog
 
+### 0.10.1
+
+- `examples` folder is not required to be in a subfolder of `docs` anymore. Fixes [#54](https://github.com/smarie/mkdocs-gallery/issues/54). PR [#92](https://github.com/smarie/mkdocs-gallery/pull/92) by [Louis-Pujol](https://github.com/Louis-Pujol).
+
 ### 0.10.0 - Support for asynchronous code
 
 - Gallery scripts now support top-level asynchronous code. PR [#90](https://github.com/smarie/mkdocs-gallery/pull/90) by [pmeier](https://github.com/pmeier)
@@ -12,7 +16,7 @@
 
  - Mayavi can now be used in gallery examples just as in `sphinx-gallery`. PR [#69](https://github.com/smarie/mkdocs-gallery/pull/69) by [GenevieveBuckley](https://github.com/GenevieveBuckley)
  - Fixed for `README.md` that contains `html` comments. Fixes [#85](https://github.com/smarie/mkdocs-gallery/issues/85). PR [#86](https://github.com/smarie/mkdocs-gallery/pull/86) by [AntoineD](https://github.com/AntoineD).
- 
+
 ### 0.7.10 - `sys.path` is not reset between code blocks
 
  - `sys.path` modifications now persist across blocks of an example. `sys.path` is still reset after each example. PR [#82](https://github.com/smarie/mkdocs-gallery/pull/82) by [Louis-Pujol](https://github.com/Louis-Pujol).
@@ -46,7 +50,7 @@
 
  - Python scripts are now correctly skipped in case of identical md5 hash. Fixes [#29](https://github.com/smarie/mkdocs-gallery/issues/29). PR [#27](https://github.com/smarie/mkdocs-gallery/pull/27) by [mchaaler](https://github.com/mchaaler).
  - Fixed error when `edit_url` is set to empty to [disable the "edit page" feature](https://www.mkdocs.org/user-guide/configuration/#edit_uri). Fixes [#32](https://github.com/smarie/mkdocs-gallery/issues/32). PR [#27](https://github.com/smarie/mkdocs-gallery/pull/27) by [mchaaler](https://github.com/mchaaler).
- 
+
 This release was yanked because of [#34](https://github.com/smarie/mkdocs-gallery/issues/34).
 
 ### 0.7.3 - Bugfix
@@ -80,7 +84,7 @@ This release was yanked because of [#34](https://github.com/smarie/mkdocs-galler
 
 Initial release with:
 
- - Basic features: 
+ - Basic features:
    - pages generation with markdown-based gallery examples. Currently only the `material` theme renders correctly
    - download buttons (both on each example and on the summaries) and page header link to the downloads section
    - subgalleries

diff --git a/docs/examples/README.md → examples/README.md b/docs/examples/README.md → examples/README.md
diff --git a/docs/examples/local_module.py → examples/local_module.py b/docs/examples/local_module.py → examples/local_module.py
diff --git a/docs/examples/no_output/README.md → examples/no_output/README.md b/docs/examples/no_output/README.md → examples/no_output/README.md
diff --git a/docs/examples/no_output/just_code.py → examples/no_output/just_code.py b/docs/examples/no_output/just_code.py → examples/no_output/just_code.py
diff --git a/docs/examples/no_output/plot_raise.py → examples/no_output/plot_raise.py b/docs/examples/no_output/plot_raise.py → examples/no_output/plot_raise.py
diff --git a/docs/examples/no_output/plot_strings.py → examples/no_output/plot_strings.py b/docs/examples/no_output/plot_strings.py → examples/no_output/plot_strings.py
diff --git a/docs/examples/no_output/plot_syntaxerror.py → examples/no_output/plot_syntaxerror.py b/docs/examples/no_output/plot_syntaxerror.py → examples/no_output/plot_syntaxerror.py
diff --git a/docs/examples/plot_00_sin.py → examples/plot_00_sin.py b/docs/examples/plot_00_sin.py → examples/plot_00_sin.py
diff --git a/docs/examples/plot_01_exp.py → examples/plot_01_exp.py b/docs/examples/plot_01_exp.py → examples/plot_01_exp.py
diff --git a/docs/examples/plot_02_seaborn.py → examples/plot_02_seaborn.py b/docs/examples/plot_02_seaborn.py → examples/plot_02_seaborn.py
diff --git a/docs/examples/plot_03_capture_repr.py → examples/plot_03_capture_repr.py b/docs/examples/plot_03_capture_repr.py → examples/plot_03_capture_repr.py
diff --git a/docs/examples/plot_04_choose_thumbnail.py → examples/plot_04_choose_thumbnail.py b/docs/examples/plot_04_choose_thumbnail.py → examples/plot_04_choose_thumbnail.py
diff --git a/docs/examples/plot_04b_provide_thumbnail.py → examples/plot_04b_provide_thumbnail.py b/docs/examples/plot_04b_provide_thumbnail.py → examples/plot_04b_provide_thumbnail.py
diff --git a/docs/examples/plot_05_unicode_everywhere.py → examples/plot_05_unicode_everywhere.py b/docs/examples/plot_05_unicode_everywhere.py → examples/plot_05_unicode_everywhere.py
diff --git a/docs/examples/plot_06_function_identifier.py → examples/plot_06_function_identifier.py b/docs/examples/plot_06_function_identifier.py → examples/plot_06_function_identifier.py
diff --git a/docs/examples/plot_07_sys_argv.py → examples/plot_07_sys_argv.py b/docs/examples/plot_07_sys_argv.py → examples/plot_07_sys_argv.py
diff --git a/docs/examples/plot_08_animations.py → examples/plot_08_animations.py b/docs/examples/plot_08_animations.py → examples/plot_08_animations.py
diff --git a/docs/examples/plot_09_plotly.py → examples/plot_09_plotly.py b/docs/examples/plot_09_plotly.py → examples/plot_09_plotly.py
diff --git a/docs/examples/plot_10_mayavi.py → examples/plot_10_mayavi.py b/docs/examples/plot_10_mayavi.py → examples/plot_10_mayavi.py
diff --git a/docs/examples/plot_11_pyvista.py → examples/plot_11_pyvista.py b/docs/examples/plot_11_pyvista.py → examples/plot_11_pyvista.py
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -22,7 +22,7 @@ plugins:
   - gallery:
       conf_script: docs/gallery_conf.py  # Base conf. Possibly modified by items below
       examples_dirs:
-        - docs/examples          # path to your example scripts, relative to mkdocs.yml
+        - examples          # path to your example scripts, relative to mkdocs.yml
         - docs/tutorials
       gallery_dirs:
         - docs/generated/gallery  # where to save gallery generated output. Note that you may or may not include them in
@@ -39,8 +39,8 @@ plugins:
       # specify the order of examples to be according to filename
       within_subsection_order: FileNameSortKey
       expected_failing_examples:
-         - docs/examples/no_output/plot_raise.py
-         - docs/examples/no_output/plot_syntaxerror.py
+         - examples/no_output/plot_raise.py
+         - examples/no_output/plot_syntaxerror.py
 
 #      min_reported_time: min_reported_time,  in conf file
       binder:

diff --git a/noxfile.py b/noxfile.py
@@ -103,7 +103,7 @@ def tests(session: PowerSession, coverage, pkg_specs):
         with open("mkdocs-no-mayavi.yml", "w") as f:
             for line in mkdocs_config:
                 if line == "      expected_failing_examples:\n":
-                    line = line + "         - docs/examples/plot_10_mayavi.py\n"
+                    line = line + "         - examples/plot_10_mayavi.py\n"
                 f.write(line)
 
     # install CI-only dependencies

diff --git a/src/mkdocs_gallery/plugin.py b/src/mkdocs_gallery/plugin.py
@@ -7,6 +7,7 @@
 The mkdocs plugin entry point
 """
 import os
+from os.path import relpath
 import re
 from pathlib import Path
 from typing import Any, Dict, List, Union
@@ -342,7 +343,7 @@ def _get_dirs_relative_to(self, dir_or_list_of_dirs: Union[str, List[str]], rel_
             dir_or_list_of_dirs = [dir_or_list_of_dirs]
 
         # Get them relative to the mkdocs source dir
-        return [Path(e).relative_to(rel_to_dir).as_posix() for e in dir_or_list_of_dirs]
+        return [Path(relpath(Path(e), start=Path(rel_to_dir))).as_posix() for e in dir_or_list_of_dirs]
 
     # def on_nav(self, nav, config, files):
     #     # Nav is already modded in on_pre_build, do not change it

diff --git a/tests/test_config.py b/tests/test_config.py
@@ -68,7 +68,7 @@ def test_full_conf(basic_mkdocs_config, monkeypatch):
     full_config = yaml_load("""
 conf_script: docs/gallery_conf.py
 examples_dirs:
-  - docs/examples
+  - examples
   - docs/tutorials
   # TODO mayavi_examples
 gallery_dirs:
@@ -83,8 +83,8 @@ def test_full_conf(basic_mkdocs_config, monkeypatch):
 compress_images: ['images', 'thumbnails']
 within_subsection_order: FileNameSortKey
 expected_failing_examples:
-   - docs/examples/no_output/plot_raise.py
-   - docs/examples/no_output/plot_syntaxerror.py
+   - examples/no_output/plot_raise.py
+   - examples/no_output/plot_syntaxerror.py
 
 # min_reported_time: min_reported_time,  in conf file
 

diff --git a/tests/test_gen_md.py b/tests/test_gen_md.py
@@ -50,7 +50,7 @@
 
 TESTS_ROOT = Path(__file__).parent
 DOCS_ROOT = TESTS_ROOT / "../docs"
-EXAMPLES_DIR = DOCS_ROOT / "examples"
+EXAMPLES_DIR = TESTS_ROOT / "../examples"
 TUTORIALS_DIR = DOCS_ROOT / "tutorials"