Salt: The docs don't build a py-modindex using newer versions of sphinx.

[bryceml]

Description of Issue/Question

Currently the docs don't include the salt/python module index when built with sphinx 2.0.1 which we recently upgraded to in order to get the pdf's to build properly. They were being built using sphinx 1.4.5 which works, 1.4.6 doesn't so that might help in narrowing down the problem.

I made this change https://github.com/saltstack/salt/commit/821f73f23da5307f6ce0ec118dd1dc32fee92b9f to get rid of the warnings about deprecated l_ function and to fix the smart quote variable renaming. It failed silently though in building the module index. The smartquotes change is needed to move from <=1.5 to >=1.6 version of sphinx, so that is correct. The other changes are related to fixing the module index but are incomplete for it to not silently fail.

Steps to Reproduce Issue

pip3 install sphinx==2.0.1
git clone https://github.com/saltstack/salt
cd salt/doc
make html

The html doesn't include a salt-modindex.html page and there is no link at the top of the contents.html page linking to it.

[bryceml]

This has been fixed, at least good enough for now. It can probably be closed. It creates the index at the file name py-modindex.html instead of salt-modindex.html. I don't know how much time we want to spend on it though.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

If this issue is closed prematurely, please leave a comment and we will gladly reopen the issue.

[stale[bot]]

Thank you for updating this issue. It is no longer marked as stale.

[sagetherage]

@bryceml how much of a problem is it, still?

[bryceml]

we just need to decide if we are ok with the link for all salt modules at the top of every page i.e. https://docs.saltstack.com/en/latest/contents.html going to py-modindex.html

Basically we try to use the py-modindex provided with sphinx and override a few things. They switched to using a deep copy instead of shallow copy so it made it harder to do that. The way it works now is kind of a hack. If we are ok with it pointing to py-modindex forever as it is now, we should remove these lines: https://github.com/saltstack/builddocs/blob/master/build_html.sh#L30-L40

[sagetherage]

is this something we could give to the Docs WG @bryceml @Ch3LL ?

[bryceml]

I don't think it hurts to have them take a look if they have time.

[sagetherage]

@saltstack/team-docs most of this is done, but see comment https://github.com/saltstack/salt/issues/52777#issuecomment-589215807

[sagetherage]

@alan-cugler @barbaricyawps

[sagetherage]

@ScriptAutomate this may be related to some of the broken links so mentioning you, here, as well

[sagetherage]

closing this as done and if changes are needed in the future let's open new tickets