Upgrade to sphinx 3.2.* and fix warnings (#3247)

Upgrades to Sphinx 3.2.* that gives us the ability to discern between cirq.qft and cirq.QFT rst files generated by autodoc which generated a warning on Mac. 

Also adding documentation to NAMED_GATESETS and fixed an indentation warning that came from the new Sphinx. 

Fixes #3202.

cirq/google/gate_sets.py

@@ -110,6 +110,9 @@
     'fsim': FSIM_GATESET,
 }
 
+document(NAMED_GATESETS,
+         """"A convenience mapping from gateset names to gatesets""")
+
 GOOGLE_GATESETS = [
     SYC_GATESET,
     SQRT_ISWAP_GATESET,

cirq/google/line/placement/greedy.py

@@ -290,11 +290,11 @@ def __init__(self, algorithm: str = 'best') -> None:
 
         Args:
             algorithm: Greedy algorithm to be used. Available options are:
-            best - runs all heuristics and chooses the best result,
-            largest_area - on every step takes the qubit which has connection
-            with the largest number of unassigned qubits, and
-            minimal_connectivity - on every step takes the qubit with minimal
-            number of unassigned neighbouring qubits.
+                best - runs all heuristics and chooses the best result,
+                largest_area - on every step takes the qubit which has
+                connection with the largest number of unassigned qubits, and
+                minimal_connectivity - on every step takes the qubit with
+                minimal number of unassigned neighbouring qubits.
         """
         self.algorithm = algorithm
 

dev_tools/build-docs.sh

@@ -44,7 +44,7 @@ rm -rf "${docs_conf_dir}/generated"
 rm -rf "${out_dir}"
 
 # Regenerate docs.
-sphinx-build -M html "${docs_conf_dir}" "${out_dir}" -W --keep-going
+sphinx-build -M html "${docs_conf_dir}" "${out_dir}" -W --keep-going -j auto
 
 # Cleanup newly generated temporary files.
 rm -rf "${docs_conf_dir}/generated"

dev_tools/conf/pip-list-dev-tools.txt

@@ -23,7 +23,7 @@ qiskit~=0.13.0
 # For generating documentation.
 pypandoc
 recommonmark >= 0.4.0
-Sphinx~=3.1.0
+Sphinx~=3.2.0
 sphinx_rtd_theme
 sphinx-markdown-tables
 

docs/conf.py

@@ -268,3 +268,6 @@ def autodoc_process(app, what: str, name: str, obj: Any, options,
 # Generate subpages for reference docs automatically.
 # http://www.sphinx-doc.org/en/master/ext/autosummary.html#generating-stub-pages-automatically
 autosummary_generate = True
+
+# to resolve name clashes between the generated files
+autosummary_filename_map = {"cirq.QFT": "cirq.QFT_deprecated"}