Improve the Sphinx build process

[javiereguiluz]

As @robfrawley explained in this comment:

The requirement of 1.3.0 for TravisCI is due to the following warning (turned into error) that halts the build due to sphinx-php overwriting code-block using sphinx versions greater than 1.3:

Warning, treated as error:
WARNING: while setting up extension sensio.sphinx.codeblock: directive 'code-block' is already
registered, it will be overridden

We may need to re-think the use of -nW opts for Travis runs, as this is incompatible with newer versions of Sphinx (which throw a warning on overridden directives), and this will become a problem at some point (as we begin to reply on newer features and need to run newer versions).

So, we need to start thinking about improving this to avoid future issues.

[xabbuh]

@javiereguiluz But this must be fixed in https://github.com/fabpot/sphinx-php. :)

[robfrawley]

@xabbuh Not necessarily, as I was unable to find any other way to register an extension (such as an overwrite or other similarly named option) outside of the Sphinx.add_directive() that is already used. The issue is newer versions of sphinx display a warning when a directive is overridden, and the CLI options we use on Travis (-nW which turn warnings into errors and cause build to stop on error) break this behavior of sphinx; php-sphinx isn't directly the problem.

[javiereguiluz]

Can anyone please help me solving this error? I still see this warning message and it's causing A LOT of issues internally on symfony.com:

Warning, treated as error:
while setting up extension sensio.sphinx.codeblock: directive 'code-block' is already registered,
it will be overridden.

Sadly, for some reasons, I can't remove the -W option in the Sphinx command to ignore warnings, so I must solve these warnings ... but I don't know what to do or where to start. Thanks!

[robfrawley]

You must use sphinx version 1.3.x if you plan to pass -nW during compilation. All later versions will throw that error due to the repeat directive registration. Beyond doing that, or not using -nW, I don't have any further solution ATM.

Are issues coming up after #8030?

[javiereguiluz]

I'm using Sphinx 1.6.2.

The only "valid" solution I found is sphinx-doc/sphinx#2451. If you put this in the codeblock.py file, the warning is gone ... but the problems aren't fixed (code blocks don't use our custom directives):

def setup(app):
    app.config.suppress_warnings.append('app.add_directive')
    # ...

[javiereguiluz]

I'm closing this because we're actively working on an alternative build system that doesn't use Sphinx.