From 5c1cbf4bb86266f27b73e0765637e0a43f31b4f1 Mon Sep 17 00:00:00 2001 From: Michael Penkov Date: Sun, 21 Aug 2022 23:14:57 +0900 Subject: [PATCH 1/5] pin sphinx versions, add explicit gallery_top label --- docs/src/auto_examples/index.rst | 261 +++++++++++++------------------ docs/src/gallery/README.txt | 2 + docs/src/support.rst | 2 +- setup.py | 14 +- 4 files changed, 120 insertions(+), 159 deletions(-) diff --git a/docs/src/auto_examples/index.rst b/docs/src/auto_examples/index.rst index 47819284b2..ca47a1738e 100644 --- a/docs/src/auto_examples/index.rst +++ b/docs/src/auto_examples/index.rst @@ -1,23 +1,23 @@ :orphan: - - -.. _sphx_glr_auto_examples: - 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`. + .. raw:: html -
+
+.. raw:: html -.. _sphx_glr_auto_examples_core: +
Core Tutorials: New Users Start Here! ------------------------------------- @@ -27,96 +27,82 @@ Understanding this functionality is vital for using gensim effectively. +.. raw:: html + +
+ + .. raw:: html
.. only:: html - .. figure:: /auto_examples/core/images/thumb/sphx_glr_run_core_concepts_thumb.png - :alt: Core Concepts + .. image:: /auto_examples/core/images/thumb/sphx_glr_run_core_concepts_thumb.png + :alt: Core Concepts - :ref:`sphx_glr_auto_examples_core_run_core_concepts.py` + :ref:`sphx_glr_auto_examples_core_run_core_concepts.py` .. raw:: html +
Core Concepts
-.. toctree:: - :hidden: - - /auto_examples/core/run_core_concepts - .. raw:: html
.. only:: html - .. figure:: /auto_examples/core/images/thumb/sphx_glr_run_corpora_and_vector_spaces_thumb.png - :alt: Corpora and Vector Spaces + .. image:: /auto_examples/core/images/thumb/sphx_glr_run_corpora_and_vector_spaces_thumb.png + :alt: Corpora and Vector Spaces - :ref:`sphx_glr_auto_examples_core_run_corpora_and_vector_spaces.py` + :ref:`sphx_glr_auto_examples_core_run_corpora_and_vector_spaces.py` .. raw:: html +
Corpora and Vector Spaces
-.. toctree:: - :hidden: - - /auto_examples/core/run_corpora_and_vector_spaces - .. raw:: html
.. only:: html - .. figure:: /auto_examples/core/images/thumb/sphx_glr_run_topics_and_transformations_thumb.png - :alt: Topics and Transformations + .. image:: /auto_examples/core/images/thumb/sphx_glr_run_topics_and_transformations_thumb.png + :alt: Topics and Transformations - :ref:`sphx_glr_auto_examples_core_run_topics_and_transformations.py` + :ref:`sphx_glr_auto_examples_core_run_topics_and_transformations.py` .. raw:: html +
Topics and Transformations
-.. toctree:: - :hidden: - - /auto_examples/core/run_topics_and_transformations - .. raw:: html
.. only:: html - .. figure:: /auto_examples/core/images/thumb/sphx_glr_run_similarity_queries_thumb.png - :alt: Similarity Queries + .. image:: /auto_examples/core/images/thumb/sphx_glr_run_similarity_queries_thumb.png + :alt: Similarity Queries - :ref:`sphx_glr_auto_examples_core_run_similarity_queries.py` + :ref:`sphx_glr_auto_examples_core_run_similarity_queries.py` .. raw:: html +
Similarity Queries
-.. toctree:: - :hidden: - - /auto_examples/core/run_similarity_queries .. raw:: html -
- - - -.. _sphx_glr_auto_examples_tutorials: +
Tutorials: Learning Oriented Lessons ------------------------------------ @@ -125,180 +111,150 @@ Learning-oriented lessons that introduce a particular gensim feature, e.g. a mod +.. raw:: html + +
+ + .. raw:: html
.. only:: html - .. figure:: /auto_examples/tutorials/images/thumb/sphx_glr_run_word2vec_thumb.png - :alt: Word2Vec Model + .. image:: /auto_examples/tutorials/images/thumb/sphx_glr_run_word2vec_thumb.png + :alt: Word2Vec Model - :ref:`sphx_glr_auto_examples_tutorials_run_word2vec.py` + :ref:`sphx_glr_auto_examples_tutorials_run_word2vec.py` .. raw:: html +
Word2Vec Model
-.. toctree:: - :hidden: - - /auto_examples/tutorials/run_word2vec - .. raw:: html
.. only:: html - .. figure:: /auto_examples/tutorials/images/thumb/sphx_glr_run_doc2vec_lee_thumb.png - :alt: Doc2Vec Model + .. image:: /auto_examples/tutorials/images/thumb/sphx_glr_run_doc2vec_lee_thumb.png + :alt: Doc2Vec Model - :ref:`sphx_glr_auto_examples_tutorials_run_doc2vec_lee.py` + :ref:`sphx_glr_auto_examples_tutorials_run_doc2vec_lee.py` .. raw:: html +
Doc2Vec Model
-.. toctree:: - :hidden: - - /auto_examples/tutorials/run_doc2vec_lee - .. raw:: html
.. only:: html - .. figure:: /auto_examples/tutorials/images/thumb/sphx_glr_run_ensemblelda_thumb.png - :alt: Ensemble LDA + .. image:: /auto_examples/tutorials/images/thumb/sphx_glr_run_ensemblelda_thumb.png + :alt: Ensemble LDA - :ref:`sphx_glr_auto_examples_tutorials_run_ensemblelda.py` + :ref:`sphx_glr_auto_examples_tutorials_run_ensemblelda.py` .. raw:: html +
Ensemble LDA
-.. toctree:: - :hidden: - - /auto_examples/tutorials/run_ensemblelda - .. raw:: html
.. only:: html - .. figure:: /auto_examples/tutorials/images/thumb/sphx_glr_run_fasttext_thumb.png - :alt: FastText Model + .. image:: /auto_examples/tutorials/images/thumb/sphx_glr_run_fasttext_thumb.png + :alt: FastText Model - :ref:`sphx_glr_auto_examples_tutorials_run_fasttext.py` + :ref:`sphx_glr_auto_examples_tutorials_run_fasttext.py` .. raw:: html +
FastText Model
-.. toctree:: - :hidden: - - /auto_examples/tutorials/run_fasttext - .. raw:: html
.. only:: html - .. figure:: /auto_examples/tutorials/images/thumb/sphx_glr_run_annoy_thumb.png - :alt: Fast Similarity Queries with Annoy and Word2Vec + .. image:: /auto_examples/tutorials/images/thumb/sphx_glr_run_annoy_thumb.png + :alt: Fast Similarity Queries with Annoy and Word2Vec - :ref:`sphx_glr_auto_examples_tutorials_run_annoy.py` + :ref:`sphx_glr_auto_examples_tutorials_run_annoy.py` .. raw:: html +
Fast Similarity Queries with Annoy and Word2Vec
-.. toctree:: - :hidden: - - /auto_examples/tutorials/run_annoy - .. raw:: html
.. only:: html - .. figure:: /auto_examples/tutorials/images/thumb/sphx_glr_run_lda_thumb.png - :alt: LDA Model + .. image:: /auto_examples/tutorials/images/thumb/sphx_glr_run_lda_thumb.png + :alt: LDA Model - :ref:`sphx_glr_auto_examples_tutorials_run_lda.py` + :ref:`sphx_glr_auto_examples_tutorials_run_lda.py` .. raw:: html +
LDA Model
-.. toctree:: - :hidden: - - /auto_examples/tutorials/run_lda - .. raw:: html
.. only:: html - .. figure:: /auto_examples/tutorials/images/thumb/sphx_glr_run_wmd_thumb.png - :alt: Word Mover's Distance + .. image:: /auto_examples/tutorials/images/thumb/sphx_glr_run_wmd_thumb.png + :alt: Word Mover's Distance - :ref:`sphx_glr_auto_examples_tutorials_run_wmd.py` + :ref:`sphx_glr_auto_examples_tutorials_run_wmd.py` .. raw:: html +
Word Mover's Distance
-.. toctree:: - :hidden: - - /auto_examples/tutorials/run_wmd - .. raw:: html
.. only:: html - .. figure:: /auto_examples/tutorials/images/thumb/sphx_glr_run_scm_thumb.png - :alt: Soft Cosine Measure + .. image:: /auto_examples/tutorials/images/thumb/sphx_glr_run_scm_thumb.png + :alt: Soft Cosine Measure - :ref:`sphx_glr_auto_examples_tutorials_run_scm.py` + :ref:`sphx_glr_auto_examples_tutorials_run_scm.py` .. raw:: html +
Soft Cosine Measure
-.. toctree:: - :hidden: - - /auto_examples/tutorials/run_scm .. raw:: html -
- - - -.. _sphx_glr_auto_examples_howtos: +
How-to Guides: Solve a Problem ------------------------------ @@ -307,96 +263,82 @@ These **goal-oriented guides** demonstrate how to **solve a specific problem** u +.. raw:: html + +
+ + .. raw:: html
.. only:: html - .. figure:: /auto_examples/howtos/images/thumb/sphx_glr_run_downloader_api_thumb.png - :alt: How to download pre-trained models and corpora + .. image:: /auto_examples/howtos/images/thumb/sphx_glr_run_downloader_api_thumb.png + :alt: How to download pre-trained models and corpora - :ref:`sphx_glr_auto_examples_howtos_run_downloader_api.py` + :ref:`sphx_glr_auto_examples_howtos_run_downloader_api.py` .. raw:: html +
How to download pre-trained models and corpora
-.. toctree:: - :hidden: - - /auto_examples/howtos/run_downloader_api - .. raw:: html
.. only:: html - .. figure:: /auto_examples/howtos/images/thumb/sphx_glr_run_doc_thumb.png - :alt: How to Author Gensim Documentation + .. image:: /auto_examples/howtos/images/thumb/sphx_glr_run_doc_thumb.png + :alt: How to Author Gensim Documentation - :ref:`sphx_glr_auto_examples_howtos_run_doc.py` + :ref:`sphx_glr_auto_examples_howtos_run_doc.py` .. raw:: html +
How to Author Gensim Documentation
-.. toctree:: - :hidden: - - /auto_examples/howtos/run_doc - .. raw:: html
.. only:: html - .. figure:: /auto_examples/howtos/images/thumb/sphx_glr_run_doc2vec_imdb_thumb.png - :alt: How to reproduce the doc2vec 'Paragraph Vector' paper + .. image:: /auto_examples/howtos/images/thumb/sphx_glr_run_doc2vec_imdb_thumb.png + :alt: How to reproduce the doc2vec 'Paragraph Vector' paper - :ref:`sphx_glr_auto_examples_howtos_run_doc2vec_imdb.py` + :ref:`sphx_glr_auto_examples_howtos_run_doc2vec_imdb.py` .. raw:: html +
How to reproduce the doc2vec 'Paragraph Vector' paper
-.. toctree:: - :hidden: - - /auto_examples/howtos/run_doc2vec_imdb - .. raw:: html
.. only:: html - .. figure:: /auto_examples/howtos/images/thumb/sphx_glr_run_compare_lda_thumb.png - :alt: How to Compare LDA Models + .. image:: /auto_examples/howtos/images/thumb/sphx_glr_run_compare_lda_thumb.png + :alt: How to Compare LDA Models - :ref:`sphx_glr_auto_examples_howtos_run_compare_lda.py` + :ref:`sphx_glr_auto_examples_howtos_run_compare_lda.py` .. raw:: html +
How to Compare LDA Models
-.. toctree:: - :hidden: - - /auto_examples/howtos/run_compare_lda .. raw:: html -
- - - -.. _sphx_glr_auto_examples_other: +
Other Resources --------------- @@ -433,27 +375,38 @@ Blog posts, tutorial videos, hackathons and other useful Gensim resources, from - ? `Deep Inverse Regression with Yelp Reviews `__ (Document Classification using Bayesian Inversion and several word2vec models, one for each class) + .. raw:: html -
+
+ +.. raw:: html + +
-.. only :: html +.. toctree:: + :hidden: + :includehidden: - .. container:: sphx-glr-footer - :class: sphx-glr-footer-gallery + /auto_examples/core/index.rst + /auto_examples/tutorials/index.rst + /auto_examples/howtos/index.rst + /auto_examples/other/index.rst - .. container:: sphx-glr-download sphx-glr-download-python +.. only:: html - :download:`Download all examples in Python source code: auto_examples_python.zip ` + .. container:: sphx-glr-footer sphx-glr-footer-gallery + .. container:: sphx-glr-download sphx-glr-download-python + :download:`Download all examples in Python source code: auto_examples_python.zip ` - .. container:: sphx-glr-download sphx-glr-download-jupyter + .. container:: sphx-glr-download sphx-glr-download-jupyter - :download:`Download all examples in Jupyter notebooks: auto_examples_jupyter.zip ` + :download:`Download all examples in Jupyter notebooks: auto_examples_jupyter.zip ` .. only:: html diff --git a/docs/src/gallery/README.txt b/docs/src/gallery/README.txt index 80ab288c48..560c047c25 100644 --- a/docs/src/gallery/README.txt +++ b/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`. diff --git a/docs/src/support.rst b/docs/src/support.rst index a28f1e0003..514b75b9b1 100644 --- a/docs/src/support.rst +++ b/docs/src/support.rst @@ -11,7 +11,7 @@ Open source support The main communication channel is the free `Gensim mailing list `_. -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 ` and `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 ` and `FAQ `_. FAQ and some useful snippets of code are maintained on GitHub: https://github.com/RARE-Technologies/gensim/wiki/Recipes-&-FAQ. diff --git a/setup.py b/setup.py index d41f668ee0..de9e0bfb36 100644 --- a/setup.py +++ b/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', From 95326170d7cef21fa67cbef5898e18e99bf65360 Mon Sep 17 00:00:00 2001 From: Michael Penkov Date: Sun, 21 Aug 2022 23:17:28 +0900 Subject: [PATCH 2/5] make flake8 happy again --- gensim/test/test_ldamodel.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gensim/test/test_ldamodel.py b/gensim/test/test_ldamodel.py index 297006b75f..7ce675e337 100644 --- a/gensim/test/test_ldamodel.py +++ b/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): From 299d9984161fafb75761a31b08b841cdd1af2f6f Mon Sep 17 00:00:00 2001 From: Michael Penkov Date: Sun, 21 Aug 2022 23:20:39 +0900 Subject: [PATCH 3/5] make flake8 happy again --- gensim/models/keyedvectors.py | 4 ++-- gensim/models/ldaseqmodel.py | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/gensim/models/keyedvectors.py b/gensim/models/keyedvectors.py index 6fb9e329d8..019d2c2652 100644 --- a/gensim/models/keyedvectors.py +++ b/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) diff --git a/gensim/models/ldaseqmodel.py b/gensim/models/ldaseqmodel.py index 0f222c9c6c..69012faf94 100644 --- a/gensim/models/ldaseqmodel.py +++ b/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 -"""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" `_. The original C/C++ implementation can be found on `blei-lab/dtm `_. From c09cf2b8148276fd381eb407ce20bd7fa5cdce54 Mon Sep 17 00:00:00 2001 From: Michael Penkov Date: Sun, 21 Aug 2022 23:27:46 +0900 Subject: [PATCH 4/5] make flake8 happy again --- gensim/models/ldamodel.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/gensim/models/ldamodel.py b/gensim/models/ldamodel.py index 10a0c60134..b5f8017f07 100755 --- a/gensim/models/ldamodel.py +++ b/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 ------- From d66e0826d0f59c0df5cbd496d1f53edbdd828f92 Mon Sep 17 00:00:00 2001 From: Michael Penkov Date: Sun, 21 Aug 2022 23:34:23 +0900 Subject: [PATCH 5/5] make flake8 happy again --- gensim/models/doc2vec.py | 3 ++- gensim/models/ldaseqmodel.py | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/gensim/models/doc2vec.py b/gensim/models/doc2vec.py index 20a739f64a..d76be81f9b 100644 --- a/gensim/models/doc2vec.py +++ b/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). diff --git a/gensim/models/ldaseqmodel.py b/gensim/models/ldaseqmodel.py index 69012faf94..8ffcb5eee6 100644 --- a/gensim/models/ldaseqmodel.py +++ b/gensim/models/ldaseqmodel.py @@ -745,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) `_. This function accepts the word to compute variance for, along with the associated sslm class object,