diff --git a/doc/setuptools.rst b/doc/setuptools.rst
index dab25fc59..2aebb16ca 100644
--- a/doc/setuptools.rst
+++ b/doc/setuptools.rst
@@ -32,15 +32,23 @@ For instance, from ``setup.py``::
             'build_sphinx': {
                 'project': ('setup.py', name),
                 'version': ('setup.py', version),
-                'release': ('setup.py', release)}},
+                'release': ('setup.py', release),
+                'source_dir': ('setup.py', 'doc')}},
     )
 
+.. note::
+
+    If you set Sphinx options directly in the ``setup()`` command, replace
+    hyphens in variable names with underscores. In the example above,
+    ``source-dir`` becomes ``source_dir``.
+
 Or add this section in ``setup.cfg``::
 
     [build_sphinx]
     project = 'My project'
     version = 1.2
     release = 1.2.0
+    source-dir = 'doc'
 
 Once configured, call this by calling the relevant command on ``setup.py``::