Remove/update lines causing build failures #8009

robfrawley · Jun 8, 2017

This pull request amends the invalid code blocks within the documentation to fix the build errors (both locally and on platform.sh). Additionally, this normalizes the dependency installation and build calls executed by both travis and platform.sh so they both use the same environment to build the documentation. This is important as currently, often one will fail while the other will succeed; this should not ever happen and they should both either fail or succeed.

See #8004 (comment) and #8004 (comment) for the origin story.

~~Note: This should likely be applied to the 3.3 branch which is where the errors originate, will update the target branch once this is confirmed.~~

robfrawley · Jun 8, 2017

Some interesting notes:

Using sphinx@1.3 allows the documentation to build withOUT error
Using sphinx@1.4 prints the invalid literal blocks WITH warnings
Using sphinx@1.5 stops on the invalid literal blocks WITH error (stopping build on first invalid block)

Sphinx 1.3 Behavior
The documentation build is successful.

Sphinx 1.4 Behavior
The documentation build prints warnings.

/home/rmf/repositories/docs/symfony-docs/controller/argument_value_resolver.rst:162: WARNING: Could not lex literal_block as "xml". Highlighting skipped.                                                          
/home/rmf/repositories/docs/symfony-docs/controller/error_pages.rst:283: WARNING: Could not lex literal_block as "xml". Highlighting skipped.                                                                      
/home/rmf/repositories/docs/symfony-docs/controller/upload_file.rst:389: WARNING: Could not lex literal_block as "xml". Highlighting skipped.                                                                      
/home/rmf/repositories/docs/symfony-docs/profiler/data_collector.rst:243: WARNING: Could not lex literal_block as "xml". Highlighting skipped.                                                                     
/home/rmf/repositories/docs/symfony-docs/security/api_key_authentication.rst:432: WARNING: Could not lex literal_block as "xml". Highlighting skipped.                                                             
/home/rmf/repositories/docs/symfony-docs/service_container/configurators.rst:144: WARNING: Could not lex literal_block as "xml". Highlighting skipped.                                                             
/home/rmf/repositories/docs/symfony-docs/service_container/expression_language.rst:22: WARNING: Could not lex literal_block as "yaml". Highlighting skipped.

Sphinx 1.5 Behavior
The documentation build stops on first error.

writing output... [ 34%] controller/argument_value_resolver                                                                                                                                                        
Exception occurred:
  File "/home/rmf/.ve/local/lib/python2.7/site-packages/sphinx/highlighting.py", line 147, in highlight_block
    type='misc', subtype='higlighting_failure')
TypeError: warner() got an unexpected keyword argument 'type'

Where to Go From Here?
So we have some options before us:

Fix the doc to build properly on newer sphinx versions (started with this PR, though I'm positive changes would be required)
Ignore the doc errors and continue to use an outdated sphinx version (completed in Amend Platform and Travis scripts to fix build failures and align their process #8010)

What direction do you guys want to take? Any thoughts?

xabbuh · Jun 9, 2017

The best option IMO would be to fix the code examples and then use Sphinx >= 1.5 to see this as soon as possible during Travis builds.

robfrawley · Jun 9, 2017

There is one additional complication when choosing this option: warnings are thrown by sphinx-php when it overwrites the code-block directive, and these warnings are turned into errors due to the -nW flags passed to sphinx during the Travis build.

As far as I can tell, there are no alternatives for sphinx-php to overwrites directives, so the warning is the current expected behavior for sphinx when this occurs (and if there was a way for sphinx-php to handle this differently, there doesn't seem much interested in doing so: #7402 (comment), #7422, fabpot/sphinx-php#33).

This means we can't use the "turn warnings into errors" flags (-nW) when building the documentation on Travis.

robfrawley · Jun 10, 2017

Rebased onto 3.3, added a subset of the changes from #8010 to align Travis and platform.sh build so they both use identical environments, and removed extra spaces from #8014 (and then squashed commits). Also, per @xabbuh I've closed #8010. We still cannot use sphinx@1.4 (or any greater version) due to the issues explained in #8009 (comment).

robfrawley · Jun 11, 2017

Is there anything about this PR that should be changed? We should get builds working...

xabbuh · Jun 12, 2017

Is the 3.3 the lowest branch that contains these wrong code examples (I mean we should fix them on every branch)?

xabbuh · Jun 12, 2017

Oh and changes to our build infrastructure should be made in the 2.7 branch to have consistent builds throughout all pull requests.

robfrawley · Jun 12, 2017

Yes, the 3.3 branch is the lowest branch where these issues were introduced (they were mainly introduced with the autowire pull requests), short of some of the extra spaces removed, which may be in lower branches. I will open a new PR with the build changes against 2.7 and update this PR to remove them.

xabbuh · Jun 12, 2017

profiler/data_collector.rst

@@ -254,7 +254,6 @@ to specify a tag that contains the template:
                    <tag name="data_collector"
                        template="data_collector/template.html.twig"
                        id="app.request_collector"
-                        <!-- priority="300" -->


this should now be added as a comment before the tag element

Updated as requested.

robfrawley · Jun 12, 2017

Ok; split out build environment changes into #8030 and squashed commits here with requested changes.

…frawley) This PR was merged into the 2.7 branch. Discussion ---------- Fix and align travis and platform build environments This pull request fixes the `platform.sh` deploy and aligns the `platform.sh` and `travis-ci.org` build to use the same version constraints and environments. Per @xabbuh in #8009 (comment) this PR has been made against the `2.7` branch. Original implementation pulled from #8010 and #8009. Changes include: - Update the `pip` version requirements pulled in by [_build/.requirements.txt](https://github.com/robfrawley/symfony-docs/blob/feature-align-travis-and-platform-build/_build/.requirements.txt) to latest releases, except for `sphinx` which must be downgraded to `1.3` until we find a solution for `sphinx-php` (which there doesn't seem to be much interest in fixing: #7402 (comment), #7422, fabpot/sphinx-php#33). - Use the same package management and constraint requirements for both `platform.sh` and `travis-ci.org` by having both utilize the `_build/.requirements.txt` file when calling `pip`. - Use the same documentation build command to compile the documentation HTML (`make`) while still calling `sphinx` with "strict mode" (or, more accurately, "turn warnings into errors mode") for `travis-ci.org`. - On `platform.sh`, since the `vitrualenv` folder is at the documentation root, remove all `rst` files contained within it (pulled in from the `pip` packages) via a `find` command, so as to ensure the build doesn't pull them in (they would never appear in the output as they don't exist in the doctree, but if they contain errors or other inconsistencies, this could cause the build to fail while reading in their sources). - `find .virtualenv -type f -name "*.rst" -delete` Commits ------- 764bc37 align travis and platform build environments

xabbuh · Jun 18, 2017

Thank you @robfrawley.

This PR was merged into the 3.3 branch. Discussion ---------- Remove/update lines causing build failures This pull request amends the invalid code blocks within the documentation to fix the build errors (both locally and on `platform.sh`). ~~Additionally, this normalizes the dependency installation and build calls executed by both `travis` and `platform.sh` so they both use the same environment to build the documentation. _This is important as currently, often one will fail while the other will succeed; this should not ever happen and they should both either fail or succeed._~~ See #8004 (comment) and #8004 (comment) for the origin story. ~~*Note: This should likely be applied to the `3.3` branch which is where the errors originate, will update the target branch once this is confirmed.*~~ Commits ------- 18ee5e2 fix invalid code lines and remove extra space

carsonbot added the Status: Needs Review label Jun 8, 2017

robfrawley mentioned this pull request Jun 8, 2017

Amend Platform and Travis scripts to fix build failures and align their process #8010

Closed

robfrawley mentioned this pull request Jun 10, 2017

Fix YAML and XML syntax errors in configuration blocks #8014

Closed

robfrawley changed the title ~~[WIP] Remove lines causing build failures~~ [WIP] Remove lines causing build failures and align travis and platform.sh build Jun 10, 2017

robfrawley force-pushed the bug-fix-build-errors branch from ab7dcdb to 4a22ca9 Compare June 10, 2017 03:11

robfrawley changed the base branch from master to 3.3 June 10, 2017 03:11

robfrawley force-pushed the bug-fix-build-errors branch from 4a22ca9 to 686a827 Compare June 10, 2017 03:14

robfrawley changed the title ~~[WIP] Remove lines causing build failures and align travis and platform.sh build~~ [WIP] Remove lines causing build failures Jun 12, 2017

robfrawley changed the title ~~[WIP] Remove lines causing build failures~~ [WIP] Remove/update lines causing build failures Jun 12, 2017

robfrawley changed the title ~~[WIP] Remove/update lines causing build failures~~ Remove/update lines causing build failures Jun 12, 2017

robfrawley mentioned this pull request Jun 12, 2017

Fix and align travis and platform build environments #8030

Merged

xabbuh reviewed Jun 12, 2017

View reviewed changes

xabbuh added this to the 3.3 milestone Jun 12, 2017

fix invalid code lines and remove extra space

18ee5e2

robfrawley force-pushed the bug-fix-build-errors branch from a10e9c3 to 18ee5e2 Compare June 12, 2017 20:37

weaverryan approved these changes Jun 13, 2017

View reviewed changes

weaverryan added Status: Reviewed and removed Status: Needs Review labels Jun 13, 2017

xabbuh approved these changes Jun 13, 2017

View reviewed changes

xabbuh merged commit 18ee5e2 into symfony:3.3 Jun 18, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Remove/update lines causing build failures #8009

Remove/update lines causing build failures #8009

Uh oh!

robfrawley commented Jun 8, 2017 •

edited

Loading

Uh oh!

robfrawley commented Jun 8, 2017 •

edited

Loading

Uh oh!

xabbuh commented Jun 9, 2017

Uh oh!

robfrawley commented Jun 9, 2017 •

edited

Loading

Uh oh!

robfrawley commented Jun 10, 2017 •

edited

Loading

Uh oh!

robfrawley commented Jun 11, 2017 •

edited

Loading

Uh oh!

xabbuh commented Jun 12, 2017

Uh oh!

xabbuh commented Jun 12, 2017

Uh oh!

robfrawley commented Jun 12, 2017

Uh oh!

xabbuh Jun 12, 2017

Uh oh!

robfrawley Jun 12, 2017 •

edited

Loading

Uh oh!

robfrawley commented Jun 12, 2017

Uh oh!

xabbuh commented Jun 18, 2017

Uh oh!

Uh oh!

Search code, repositories, users, issues, pull requests...

Uh oh!

Remove/update lines causing build failures #8009

Remove/update lines causing build failures #8009

Uh oh!

Conversation

robfrawley commented Jun 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robfrawley commented Jun 8, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xabbuh commented Jun 9, 2017

Uh oh!

robfrawley commented Jun 9, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robfrawley commented Jun 10, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robfrawley commented Jun 11, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xabbuh commented Jun 12, 2017

Uh oh!

xabbuh commented Jun 12, 2017

Uh oh!

robfrawley commented Jun 12, 2017

Uh oh!

xabbuh Jun 12, 2017

Choose a reason for hiding this comment

Uh oh!

robfrawley Jun 12, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robfrawley commented Jun 12, 2017

Uh oh!

xabbuh commented Jun 18, 2017

Uh oh!

Uh oh!

robfrawley commented Jun 8, 2017 •

edited

Loading

robfrawley commented Jun 8, 2017 •

edited

Loading

robfrawley commented Jun 9, 2017 •

edited

Loading

robfrawley commented Jun 10, 2017 •

edited

Loading

robfrawley commented Jun 11, 2017 •

edited

Loading

robfrawley Jun 12, 2017 •

edited

Loading