pin sphinx versions, add explicit gallery_top label (#3383)

* pin sphinx versions, add explicit gallery_top label

* make flake8 happy again

* make flake8 happy again

* make flake8 happy again

* make flake8 happy again

docs/src/gallery/README.txt

@@ -1,5 +1,7 @@
 Documentation
 =============
 
+.. _gallery_top:
+
 We welcome contributions to our documentation via GitHub pull requests, whether it's fixing a typo or authoring an entirely new tutorial or guide.
 If you're thinking about contributing documentation, please see :ref:`sphx_glr_auto_examples_howtos_run_doc.py`.

docs/src/support.rst

@@ -11,7 +11,7 @@ Open source support
 
 The main communication channel is the free `Gensim mailing list <https://groups.google.com/group/gensim>`_.
 
-This is the preferred way to ask for help, report problems and share insights with the community. Newbie questions are perfectly fine, as long as you've read the :ref:`tutorials <sphx_glr_auto_examples>` and `FAQ <https://github.com/RaRe-Technologies/gensim/wiki/Recipes-&-FAQ>`_.
+This is the preferred way to ask for help, report problems and share insights with the community. Newbie questions are perfectly fine, as long as you've read the :ref:`tutorials <gallery_top>` and `FAQ <https://github.com/RaRe-Technologies/gensim/wiki/Recipes-&-FAQ>`_.
 
 FAQ and some useful snippets of code are maintained on GitHub: https://github.com/RARE-Technologies/gensim/wiki/Recipes-&-FAQ.
 

gensim/models/doc2vec.py

@@ -1137,7 +1137,8 @@ def __iter__(self):
 
 class TaggedLineDocument:
     def __init__(self, source):
-        """Iterate over a file that contains documents: one line = :class:`~gensim.models.doc2vec.TaggedDocument` object.
+        """Iterate over a file that contains documents:
+        one line = :class:`~gensim.models.doc2vec.TaggedDocument` object.
 
         Words are expected to be already preprocessed and separated by whitespace. Document tags are constructed
         automatically from the document line number (each document gets a unique integer tag).

gensim/models/keyedvectors.py

@@ -517,7 +517,7 @@ def get_mean_vector(self, keys, weights=None, pre_normalize=True, post_normalize
             elif not ignore_missing:
                 raise KeyError(f"Key '{key}' not present in vocabulary")
 
-        if(total_weight > 0):
+        if total_weight > 0:
             mean = mean / total_weight
         if post_normalize:
             mean = matutils.unitvec(mean).astype(REAL)
@@ -1252,7 +1252,7 @@ def n_similarity(self, ws1, ws2):
             Similarities between `ws1` and `ws2`.
 
         """
-        if not(len(ws1) and len(ws2)):
+        if not (len(ws1) and len(ws2)):
             raise ZeroDivisionError('At least one of the passed list is empty.')
         mean1 = self.get_mean_vector(ws1, pre_normalize=False)
         mean2 = self.get_mean_vector(ws2, pre_normalize=False)

gensim/models/ldamodel.py

@@ -314,7 +314,8 @@ def load(cls, fname, *args, **kwargs):
 
 
 class LdaModel(interfaces.TransformationABC, basemodel.BaseTopicModel):
-    """Train and use Online Latent Dirichlet Allocation model as presented in `'Online Learning for LDA' by Hoffman et al.`_
+    """Train and use Online Latent Dirichlet Allocation model as presented in
+    `'Online Learning for LDA' by Hoffman et al.`_
 
     Examples
     -------

gensim/models/ldaseqmodel.py

@@ -4,7 +4,8 @@
 # Licensed under the GNU LGPL v2.1 - http://www.gnu.org/licenses/lgpl.html
 # Based on Copyright (C) 2016 Radim Rehurek <radimrehurek@seznam.cz>
 
-"""Lda Sequence model, inspired by `David M. Blei, John D. Lafferty: "Dynamic Topic Models"
+"""Lda Sequence model, inspired by
+`David M. Blei, John D. Lafferty: "Dynamic Topic Models"
 <https://mimno.infosci.cornell.edu/info6150/readings/dynamic_topic_models.pdf>`_.
 The original C/C++ implementation can be found on `blei-lab/dtm <https://github.com/blei-lab/dtm>`_.
 
@@ -744,7 +745,8 @@ def update_zeta(self):
         return self.zeta
 
     def compute_post_variance(self, word, chain_variance):
-        r"""Get the variance, based on the `Variational Kalman Filtering approach for Approximate Inference (section 3.1)
+        r"""Get the variance, based on the
+        `Variational Kalman Filtering approach for Approximate Inference (section 3.1)
         <https://mimno.infosci.cornell.edu/info6150/readings/dynamic_topic_models.pdf>`_.
 
         This function accepts the word to compute variance for, along with the associated sslm class object,

gensim/test/test_ldamodel.py

@@ -33,7 +33,7 @@
 def test_random_state():
     testcases = [np.random.seed(0), None, np.random.RandomState(0), 0]
     for testcase in testcases:
-        assert(isinstance(utils.get_random_state(testcase), np.random.RandomState))
+        assert isinstance(utils.get_random_state(testcase), np.random.RandomState)
 
 
 class TestLdaModel(unittest.TestCase, basetmtests.TestBaseTopicModel):

setup.py

@@ -297,11 +297,17 @@ def run(self):
 #   https://packaging.python.org/discussions/install-requires-vs-requirements/
 #
 
+#
+# We pin the Sphinx-related packages to specific versions here because we want
+# our documentation builds to be reproducible.  Different versions of Sphinx
+# can generate slightly different output, and because we keep some of the output
+# under version control, we want to keep these differences to a minimum.
+#
 docs_testenv = core_testenv + distributed_env + visdom_req + [
-    'sphinx',
-    'sphinx-gallery',
-    'sphinxcontrib.programoutput',
-    'sphinxcontrib-napoleon',
+    'sphinx==5.1.1',
+    'sphinx-gallery==0.11.1',
+    'sphinxcontrib.programoutput==0.17',
+    'sphinxcontrib-napoleon==0.7',
     'matplotlib',  # expected by sphinx-gallery
     'memory_profiler',
     'annoy',