DOC: Improper configuration for LaTeX documentation

[rossbar]

The conf.py in doc/source lists has the following configuration building latex documents:

numpy/doc/source/conf.py

Lines 158 to 166 in 3f11db4

	# Grouping the document tree into LaTeX files. List of tuples
	# (source start file, target name, title, author, document class [howto/manual]).
	_stdauthor = 'Written by the NumPy community'
	latex_documents = [
	('reference/index', 'numpy-ref.tex', 'NumPy Reference',
	_stdauthor, 'manual'),
	('user/index', 'numpy-user.tex', 'NumPy User Guide',
	_stdauthor, 'manual'),
	]

However, user/index was removed in 22356fc as part of the NEP 44 restructuring, which means this configuration is no longer valid and attempting to build the latex docs (as is done for the documentation release process, for example) will fail as a result.

Either doc/source/user/index.rst should be added back or the sphinx configuration needs to be updated with a new start file for the user guide.

Reproducing code example:

Within a properly setup environment for building docs:

cd doc && make latex

Error message:

The following warning is given by sphinx:

WARNING: "latex_documents" config value references unknown document user/index

The build will terminate without attempting to compile numpy-user.tex.

Numpy/Python version information:

Python 3.8.3 | numpy v1.20.0.dev0+3f11db4

[melissawm]

I'm not sure what's the best way forward here, since the old "User Guide" would now be equivalent to everything under "For users" on the main docs page. Maybe adding a index.rst that contains just the links to those sections?

[rossbar]

Yeah I wasn't sure either - I have a proposal in #16373 that tries to achieve the best of both worlds, i.e. leave the html docs relatively untouched (by reintroducing index as an orphan), but adds back the necessary component for the latex build.

If that solution sounds okay, please take a look at the toctree in #16373 to see if the listings there should be updated.

[mattip]

It would be nice if we could hide the unwanted links with an .. only directive. But it doesn't work, there are a few "won't fix" issues like this one about this.

[rossbar]

Thanks for the info @mattip , I'll give .. only a try.

[rossbar]

AFAICT after trying reading about .. only and .. ifconfig these directives are helpful for control which content within files is presented, but not whether the file itself is included for different configurations. We could include a .. only directive in user/index.rst, but that wouldn't suppress the generation of the html file itself, it would just make the page itself blank.