[Documentation]: strange indexing of tutorials

[bendichter]

What would you like changed or added to the documentation and why?

@oruebel do you know how this is generated?

Do you have any interest in helping write or edit the documentation?

No.

Code of Conduct

• I agree to follow this project's Code of Conduct
• Have you checked the Contributing document?
• Have you ensured this change was not already requested?

[oruebel]

I triggered a rebuild of the docs on RTD just in case, but (not surprisingly) that did not fix the issue. Strangely, when I build the docs locally the index looks fine.

My guess is that maybe something has changed in sphinx-gallery and that RTD is using a different version than what I have installed locally. In terms of code, my initial guess is that this probably due to the customization we do to sort the tutorials within each section, which is here:

pynwb/docs/source/conf.py

Lines 63 to 137 in d40dd30

	from sphinx_gallery.sorting import ExplicitOrder
	from sphinx_gallery.sorting import ExampleTitleSortKey
	class CustomSphinxGallerySectionSortKey(ExampleTitleSortKey):
	"""
	Define the key to be used to sort sphinx galleries sections
	:param src_dir : The source directory.
	:type srd_dir: str
	"""
	# Define a partial ordered list of galleries for all subsections. Galleries not
	# listed here will be added in alphabetical order based on title after the
	# explicitly listed galleries
	GALLERY_ORDER = {
	'general': ['file.py'],
	# Sort domain-specific tutorials based on domain to group tutorials belonging to the same domain
	'domain': [
	"ecephys.py",
	"ophys.py",
	"plot_icephys.py",
	"plot_icephys_pandas.py",
	"icephys.py",
	"plot_behavior.py",
	"images.py",
	"brain_observatory.py"
	],
	'advanced_io': []
	}
	def __call__(self, filename):
	"""
	Compute index to use for sorting galleries.
	Return the explicit index of the gallery if defined as part of self.GALLERY_ORDER
	and otherwise compute a score based on the title of the gallery to ensure galleries
	are sorted alphabetically by default
	"""
	import string
	import math
	# Get the ordered list of gallery files for the current source dir
	explicit_order = self.GALLERY_ORDER.get(os.path.basename(self.src_dir), [])
	# If the file is in the explicit order then return its index
	if filename in explicit_order:
	sort_index = explicit_order.index(filename)
	# Else sort alphabetically based on the title by computing a corresponding
	# floating point index based on the characters of the titles
	else:
	title = super().__call__(filename)
	# map the characters of the title to a floating point number
	# based on the numerical index of the individual lowercase characters
	sort_index = len(explicit_order) # all explicitly ordered galleries come first
	for i, v in enumerate(title.lower()):
	# get the index of the current character
	curr_index = (string.ascii_lowercase.index(v)
	if v in string.ascii_lowercase
	else len(string.ascii_lowercase))
	# shift the value based on its position in the title string and
	# add it to the sort_index value
	sort_index += curr_index / math.pow(10, ((i+1) * 2))
	return sort_index
	sphinx_gallery_conf = {
	# path to your examples scripts
	'examples_dirs': ['../gallery'],
	# path where to save gallery generated examples
	'gallery_dirs': ['tutorials'],
	'subsection_order': ExplicitOrder(['../gallery/general', '../gallery/domain', '../gallery/advanced_io']),
	'backreferences_dir': 'gen_modules/backreferences',
	'min_reported_time': 5,
	'remove_config_comments': True,
	'within_subsection_order': CustomSphinxGallerySectionSortKey,
	}

The quick fix would be to simply not show the [+] for the tutorials by reducing the depth of the index.

[oruebel]

Ok, I just upgraded my local version of sphinx_gallery from 10.x to the latest version 13 and am seeing the same issue, i.e., this appears to be a bug in sphinx_gallery or some breaking change in the API that requires updates in our code.

[oruebel]

Ok, I tried with sphinx-gallery v 0.13, 0.12.2, 0.11.1, and 0.10.1. 0.10.1 works correctly and all the newer versions show the same issue, i.e., it looks something broke in 0.11. As an immediate fix, I think we can just pin the version of spinx-gallery and then investigate further whether this is something that requires a fix in sphinx-gallery or on our end.

[oruebel]

#1728 addresses this issue by fixing the version of sphinx-gallery to 0.10.1.

I also filed an issue ticket on the sphinx-gallery repo sphinx-gallery/sphinx-gallery#1152 . Looking at the changelog for sphinx-gallery 0.11.0 it looks like they fixed a very similar issue in that release sphinx-gallery/sphinx-gallery#935 . Maybe that fix did not cover our case.