Error when examples source dir is located outside docs dir

[GenevieveBuckley]

The mkdcos-gallery webpage says that you can have your source gallery examples folder located either inside or outside the base mkdocs docs directory. But when I try to put the examples outside the docs directory, I get an error.

Situation

The mkdocs-gallery docs main page says:

...the folder can be located inside the usual mkdocs source folder:

docs/                    # base mkdocs source directory
└── examples/            # base 'Gallery of Examples' directory
└── README.md

or not

examples/            # base 'Gallery of Examples' directory
└── README.md
docs/                # base mkdocs source directory

To reproduce

1. Create a virtual environment, and make sure the following packages are installed:

mkdocs==1.2.4
mkdocs-material
mkdocs-gallery
jupyter 
numpy
matplotlib

2. Clone this example repository, and fetch the tags:

git clone https://github.com/GenevieveBuckley/mkdocs-example.git
cd mkdocs-example
git fetch --tags

3. Checkout the first, working example, where the gallery examples live in a folder underneath the main docs folder. The documentation build succeeds.

git checkout tags/examples-inside-docs-folder -b examples-inside-docs-folder-main
mkdocs build
mkdocs serve

After checking that the build succeeds, you can delete the generated docs content:

rm -rf site
rm -rf docs/generated

4. Now, checkout the second example tag, where the examples have been moved outside the docs folder (so they are at the same heirarchy level). This time, the documentation build fails.

git checkout tags/broken-example -b broken-example-main
mkdocs build

What happened

A value error is raised at this line:

mkdocs-gallery/src/mkdocs_gallery/plugin.py

Line 250 in 68791f5

examples_dirs = self._get_dirs_relative_to(self.config['examples_dirs'], rel_to_dir=config['docs_dir'])

ValueError: '/Users/genevieb/Documents/GitHub/mkdocs-example-2/docs/examples' is not in the subpath of '/Users/genevieb/Documents/GitHub/mkdocs-example-2/docs/docs' OR one path is relative and the other is absolute.

Full error message:

mkdocs build
INFO     -  generating gallery...
generating gallery for /Users/genevieb/Documents/GitHub/mkdocs-example-2/docs/do
INFO     -  computation time summary:
INFO     -      - examples/plot_example.py:   0.00 sec   0.0 MB
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory:
            /Users/genevieb/Documents/GitHub/mkdocs-example-2/docs/site
Traceback (most recent call last):
  File "/Users/genevieb/mambaforge/envs/mkdocs-gallery-dev/bin/mkdocs", line 10, in <module>
    sys.exit(cli())
  File "/Users/genevieb/mambaforge/envs/mkdocs-gallery-dev/lib/python3.10/site-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/Users/genevieb/mambaforge/envs/mkdocs-gallery-dev/lib/python3.10/site-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/Users/genevieb/mambaforge/envs/mkdocs-gallery-dev/lib/python3.10/site-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/Users/genevieb/mambaforge/envs/mkdocs-gallery-dev/lib/python3.10/site-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/Users/genevieb/mambaforge/envs/mkdocs-gallery-dev/lib/python3.10/site-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/Users/genevieb/mambaforge/envs/mkdocs-gallery-dev/lib/python3.10/site-packages/mkdocs/__main__.py", line 187, in build_command
    build.build(config.load_config(**kwargs), dirty=not clean)
  File "/Users/genevieb/mambaforge/envs/mkdocs-gallery-dev/lib/python3.10/site-packages/mkdocs/commands/build.py", line 282, in build
    files = config['plugins'].run_event('files', files, config=config)
  File "/Users/genevieb/mambaforge/envs/mkdocs-gallery-dev/lib/python3.10/site-packages/mkdocs/plugins.py", line 102, in run_event
    result = method(item, **kwargs)
  File "/Users/genevieb/temp/gallery/mkdocs-gallery/src/mkdocs_gallery/plugin.py", line 250, in on_files
    examples_dirs = self._get_dirs_relative_to(self.config['examples_dirs'], rel_to_dir=config['docs_dir'])
  File "/Users/genevieb/temp/gallery/mkdocs-gallery/src/mkdocs_gallery/plugin.py", line 305, in _get_dirs_relative_to
    return [Path(e).relative_to(rel_to_dir).as_posix() for e in dir_or_list_of_dirs]
  File "/Users/genevieb/temp/gallery/mkdocs-gallery/src/mkdocs_gallery/plugin.py", line 305, in <listcomp>
    return [Path(e).relative_to(rel_to_dir).as_posix() for e in dir_or_list_of_dirs]
  File "/Users/genevieb/mambaforge/envs/mkdocs-gallery-dev/lib/python3.10/pathlib.py", line 818, in relative_to
    raise ValueError("{!r} is not in the subpath of {!r}"
ValueError: '/Users/genevieb/Documents/GitHub/mkdocs-example-2/docs/examples' is not in the subpath of '/Users/genevieb/Documents/GitHub/mkdocs-example-2/docs/docs' OR one path is relative and the other is absolute.

What to do?

Either the mkdocs-gallery documentation should be updated, or a change made to the code so this behaviour is supported.

It's probably easiest to update the docs page than to change the code - I had a look at it but am having a hard time with interactive debugging. The easiest starting point for me is mkdocs build but I can't easily drop into the python debugger when it hits an error. I can maybe try to call the mkdocs build function from python directly, but then I need to also set up the mkdocs config object to pass in and it's not as convenient. Is there an easier way I should try?

[smarie]

Thanks @GenevieveBuckley ! I wish all issue reports would be as nice, well-structured and undestandable as this :)

Inteactive debugging is indeed mandatory to develop. In PyCharm you can do create a run/debug configuration with module name mkdocs.__main__ and parameter build like this:

EDIT: note that you may wish to select mkdocs-gallery\.nox\tests-3-9\Scripts\python.exe as the Python interpreter used to debug this project as shown below