Updated Sphinx configuration instructions #3332
Conversation
|
I think you did something wrong, in the end it should look like this: https://github.com/WouterJ/symfony-docs/blob/travis_integration/conf.py#L34 |
|
The problem might be that people are not familiar with our use of the ellipses. Thus, you might be tempted to append the whole |
|
but this tip suggests that you should remove the other extensions. |
|
Yeah, the tip is not clear enough. It should be rewritten in such that you have to add the Symfony docs related extensions to the list of already configured extensions if they exist. |
|
On second thoughts yes the tip can be misleading; I'll think about another phraisng |
| @@ -211,6 +211,31 @@ Installing the Sphinx extensions | |||
| # set URL for API links | |||
| api_url = 'http://api.symfony.com/master/%s' | |||
|
|
|||
| .. tip:: | |||
|
|
|||
| It seems that with newest Sphinx versions you may receive an error such | |||
There was a problem hiding this comment.
It seems sounds too unreliable... what about With newest Sphinx versions you may sometimes receive [...]? That, if the errors happen only sometimes.
There was a problem hiding this comment.
it doesn't depend on the sphinx version. It depends on whether someone understands our ellipses usage or not.
There was a problem hiding this comment.
The note comes from the possibility (based on what we saw at the hack day), that the newest version of Sphinx may have extensions = [] instead of extensions = ['lots of things'] (meaning it's blank in newer versions). That was part of the reason for the confusion.
This PR was merged into the 2.3 branch. Discussion ---------- [WIP] Travis integration | Q | A | --- | --- | Doc fix? | no | New docs? | no | Applies to | all | Fixed tickets | #2722, #3332 ##### Todo - [x] Using sparse checkout - [x] Update contributing docs - [ ] Squashing commits - [ ] Activate Travis hook (@fabpot) Commits ------- 37eb137 Update documentation 8dec729 sparse checkouts b6f693e Added CMF b1d9e62 Revert changes 6cad008 Updated travis config c515613 Added .gitignore 85b1b02 Try to supress bundle doc warnings f3cb8b1 Fixed submodules 71a2ff4 Added needed config files d312683 Added sphinx files
|
Closing this now that we've gone a step further and included the build details in the repository itself :). Though, perhaps now we can take a look back at these instructions and update them to use the new build stuff - I don't think we've done that yet. Cheers! |
|
Well, there's not much left to do besides installing Sphinx and its extensions and running |
|
@xabbuh - you're right, I don't know why I thought that needed more work. Cheers! |
Hi,
While starting contributing, I ran into an error in Sphinx configuration.
The syntax of the configuration file should be slightly modified, here I propose to add a "tip", for users who may encounter the same issue.