Repository: sphinx-gallery/sphinx-gallery

Issue:
Allow pathlib.Path to backreferences_dir option
https://github.com/sphinx-gallery/sphinx-gallery/pull/571 checks that `backreferences_dir` is either `None` or `str`. It would be nice to allow `pathlib.Path` objects too.

Discussion:
codecov-io: # [Codecov](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/638?src=pr&el=h1) Report
> Merging [#638](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/638?src=pr&el=desc) into [master](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/commit/acffdaa9c1fe4581e917fe3fc93f11d5655a8f26?src=pr&el=desc) will **increase** coverage by `0.06%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/638/graphs/tree.svg?width=650&token=K4eytvhwU5&height=150&src=pr)](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/638?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master     #638      +/-   ##
==========================================
+ Coverage   97.71%   97.78%   +0.06%     
==========================================
  Files          31       31              
  Lines        3194     3201       +7     
==========================================
+ Hits         3121     3130       +9     
+ Misses         73       71       -2
```


| [Impacted Files](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/638?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [sphinx\_gallery/gen\_gallery.py](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/638/diff?src=pr&el=tree#diff-c3BoaW54X2dhbGxlcnkvZ2VuX2dhbGxlcnkucHk=) | `96.78% <100%> (+0.61%)` | :arrow_up: |
| [sphinx\_gallery/tests/test\_gen\_gallery.py](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/638/diff?src=pr&el=tree#diff-c3BoaW54X2dhbGxlcnkvdGVzdHMvdGVzdF9nZW5fZ2FsbGVyeS5weQ==) | `100% <100%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/638?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/638?src=pr&el=footer). Last update [acffdaa...8a2522a](https://codecov.io/gh/sphinx-gallery/sphinx-gallery/pull/638?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).


Patch:
diff --git a/doc/configuration.rst b/doc/configuration.rst
index e7568c8..840f067 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -331,9 +331,9 @@ The path you specify in ``backreferences_dir`` (here we choose
 ``gen_modules/backreferences``) will be populated with
 ReStructuredText files. Each will contain a reduced version of the
 gallery specific to every function used across all the examples
-galleries and belonging to the modules listed in ``doc_module``. Keep
-in mind that the path set in ``backreferences_dir`` is **relative** to the
-``conf.py`` file.
+galleries and belonging to the modules listed in ``doc_module``.
+``backreferences_dir` should be a string or ``pathlib.Path`` object that is
+**relative** to the ``conf.py`` file, or ``None``. It is ``None`` by default.
 
 Then within your sphinx documentation ``.rst`` files you write these
 lines to include this reduced version of the Gallery, which has
diff --git a/sphinx_gallery/gen_gallery.py b/sphinx_gallery/gen_gallery.py
index 8ad3d20..4a460c7 100644
--- a/sphinx_gallery/gen_gallery.py
+++ b/sphinx_gallery/gen_gallery.py
@@ -17,6 +17,7 @@ from datetime import timedelta, datetime
 from importlib import import_module
 import re
 import os
+import pathlib
 from xml.sax.saxutils import quoteattr, escape
 
 from sphinx.util.console import red
@@ -206,11 +207,16 @@ def _complete_gallery_conf(sphinx_gallery_conf, src_dir, plot_gallery,
     # Make it easy to know which builder we're in
     gallery_conf['builder_name'] = builder_name
     gallery_conf['titles'] = {}
-    # Ensure 'backreferences_dir' is str or None
+    # Ensure 'backreferences_dir' is str, pathlib.Path or None
     backref = gallery_conf['backreferences_dir']
-    if (not isinstance(backref, str)) and (backref is not None):
+    if (not isinstance(backref, (str, pathlib.Path))) and (backref is not None):
         raise ValueError("The 'backreferences_dir' parameter must be of type "
-                         "str or None, found type %s" % type(backref))
+                         "str, pathlib.Path or None, "
+                         "found type %s" % type(backref))
+    # if 'backreferences_dir' is pathlib.Path, make str for Python <=3.5
+    # compatibility
+    if isinstance(backref, pathlib.Path):
+        gallery_conf['backreferences_dir'] = str(backref)
 
     if not isinstance(gallery_conf['css'], (list, tuple)):
         raise TypeError('gallery_conf["css"] must be list or tuple, got %r'


Test patch:
diff --git a/sphinx_gallery/tests/test_gen_gallery.py b/sphinx_gallery/tests/test_gen_gallery.py
index 1b1de2e..4f3dc01 100644
--- a/sphinx_gallery/tests/test_gen_gallery.py
+++ b/sphinx_gallery/tests/test_gen_gallery.py
@@ -11,6 +11,7 @@ import codecs
 import os
 import sys
 import re
+import pathlib
 
 import pytest
 
@@ -381,5 +382,17 @@ def test_backreferences_dir_config(sphinx_app_wrapper):
         parse_config(sphinx_app_wrapper.create_sphinx_app())
 
 
+@pytest.mark.conf_file(content="""
+import pathlib
+
+sphinx_gallery_conf = {
+    'backreferences_dir': pathlib.Path('.'),
+}""")
+def test_backreferences_dir_pathlib_config(sphinx_app_wrapper):
+    """Tests pathlib.Path does not raise exception."""
+    from sphinx_gallery.gen_gallery import parse_config
+    parse_config(sphinx_app_wrapper.create_sphinx_app())
+
+
 def test_write_computation_times_noop():
     write_computation_times(None, None, [[[0]]])