Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated Sphinx configuration instructions #3332

Closed
wants to merge 1 commit into from
Closed

Updated Sphinx configuration instructions #3332

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 27 additions & 2 deletions contributing/documentation/format.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,8 +181,8 @@ Installing the Sphinx extensions

* Download the extension from the `source`_ repository

* Copy the ``sensio`` directory to the ``_exts`` folder under your source
folder (where ``conf.py`` is located)
* Copy the ``sensio`` directory to the ``_exts`` (you may have to create it) folder under your source
folder (the source folder is where ``conf.py`` is located)

* Add the following to the ``conf.py`` file:

Expand Down Expand Up @@ -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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems sounds too unreliable... what about With newest Sphinx versions you may sometimes receive [...]? That, if the errors happen only sometimes.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it doesn't depend on the sphinx version. It depends on whether someone understands our ellipses usage or not.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

``There is a syntax error in your configuration file: invalid syntax (conf.py, line 268)``
This happens because you try to append "extensions" to an empty array.

Look for this line near the top of ``config.py``

.. code-block:: py

extensions = []

Replace it by:

.. code-block:: py

extensions = ['sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode']

And you can now remove this line you added previously:

.. code-block:: py

extensions = [..., 'sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode']


.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org/
.. _documents: https://github.com/symfony/symfony-docs
Expand Down