Running Sphinx multiple times produces 'already registered' warnings.

[nakato]

When running sphinx multiple times from a python instance, such as by setup_command.BuildDoc.run(self) twice, sphinx produces warnings about roles/directives/nodes being already registered, and fails if warningiserror is enabled.

The warnings were added in Issue #1962 and supress_warnings were added in #2451

The use case where we are hitting this is here:
https://github.com/openstack-dev/pbr/blob/a5d46d5ce7b690997fee7601d459231e05b965dd/pbr/builddoc.py#L198

And can be seen when running python setup.py build_sphinx with our testing package:
https://github.com/openstack-dev/pbr/tree/a5d46d5ce7b690997fee7601d459231e05b965dd/pbr/tests/testpackage

Would it be reasonable to check if the same obj is being re-registered to the same name, and if they are equal not raise a warning, or is there a more appropriate way I could handling this?

[tk0miya]

In my short investigation:
Now sphinx has registered roles, directives and nodes to docutils. And docutils registers them on module global variables. So they are kept registered in a same process.
On the other hand, a lifecycle of the application object of sphinx is shorter than a process. It seems the builddoc.py calls setup_command.BuildDoc.run() twice. so the extensions are also loaded twice and warned as already registered.

[nakato]

Yes, I understand why this is happening.

I'm wondering if there's a more appropriate way to generate multiple documents in a single run than we are doing currently, or if there is a way we can extend the checks that throw the warnings to be more restrictive. Should Sphinx be throwing an error if the extension that we are loading is the same as the extension that is loaded, or should it see that the extension is already loaded and is not a different extension, and just move on? Or is multiple runs of sphinx in a single process something that is completely unsupported?

[tk0miya]

I fixed this in #2965.
Could you check it please?
If it's okay, I will merge it.