I've been trying to build the documentation for a python project using Sphinx with the rtd theme, and have encountered the following error:
make_toctree() got an unexpected keyword argument 'titles_only'
As far as I can tell, this error isn't reported/described online (yet). The documentation was building correctly about six months ago, and there have been no changes to the configuration of the project, which suggests to me that this error comes from python and sphinx, rather than the project itself.
I have tried removing and reinstalling sphinx and the rtd theme, both from synaptic and from pip --user, (and have tried having only one of these installed/active at a given time), and the error seems to persist.
It seems like titles_only should be a valid keyword to pass to the sphinx library, so this suggests that there might have been some sort of API change that has broken the rtd theme?
I've spent a couple hours now just trying to rebuild the documentation, and don't quite have time to dig into this further, so I thought I'd ask Stackoverflow just in case someone else had encountered this and knew the fix.
edit: package version numbers could be helpful
sphinx-rtd-theme==0.1.9
sphinxcontrib-fulltoc==1.2.0
edit: these commands are used to bulid the documentation
sphinx-apidoc -fe -o . ./$PROJECTNAME
make SPHINXOPTS='-W' clean html
The makefile is
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = Neurotools
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
This sphinx configuration file is a few years old, and I'm not 100% sure what modifications have been made in the history of the project. I've (hopfully) removed identifying information from the contents:
# -- General configuration ------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.mathjax',
'sphinx.ext.viewcode',
'sphinx.ext.napoleon',
]
# special code to handle different versions of sphinx gracefully
import sys, os
assert 'sphinx' in sys.modules
mathjax_path="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
sys.path.insert(0,os.path.abspath("./PROJECTNAMEPATH/"))
mod = __import__('sphinx')
potential_version_variable_names = ['__version__','__VERSION__','VERSION','version','version_info']
loaded_version = None
if loaded_version is None:
for vname in potential_version_variable_names:
if vname in mod.__dict__:
# try to find version information,
# just hope and pray it's a string if it exists
# take only the first line if multiple lines exist
loaded_version = mod.__dict__[vname]
break
if loaded_version is None:
try:
loaded_version = pkg_resources.get_distribution(package).version
except:
pass
if loaded_version is None:
if package in installed_via_pip:
p = installed_via_pip[package]
if p.has_version:
loaded_version = p.version
if loaded_version is None:
sys.stdout.write('\tNo sphinx version information found.')
else:
loaded_version = loaded_version.split('\n')[0]
loaded_version = tuple(map(int,loaded_version.split('.')))
sys.stdout.write('\tSphinx version '+str(loaded_version)+'\n')
if loaded_version>=(1,4):
extensions += [
'sphinxcontrib.fulltoc',
'sphinx.ext.githubpages',]
sys.stdout.write('\tAdding github pages module\n')
else:
sys.stdout.write('\tPlease update Sphinx to use the github pages module\n')
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'PROJECTNAME'
copyright = u'2017, AUTHORS'
author = u'AUTHORS'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'2'
# The full version, including alpha/beta/rc tags.
release = u'2'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store','extract_doc.py']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
#html_theme = 'alabaster'
html_theme = "sphinx_rtd_theme"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'PROJECTNAME'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'PROJECTNAME.tex', u'PROJECTNAME Documentation',
u'AUTHORS', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'PROJECTNAME', u'PROJECTNAME Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'PROJECTNAME', u'PROJECTNAME Documentation',
author, 'PROJECTNAME', 'One line description of project.',
'Miscellaneous'),
]
# -- Options for Epub output ----------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
epub_author = author
epub_publisher = author
epub_copyright = copyright
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
####### FURHTHER CUSTOMIZATION ########
html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'], }
html_theme_options = {'navigation_depth': 5,}
extensions += ['sphinx.ext.autosummary',]
autodoc_default_flags = ['members']
autosummary_gerenerate = True
exclude_patterns = ['_auto/*']
autodoc_member_order = 'bysource'
