Fix docs and create CI job to build them (#423)

.github/workflows/build_docs.yml

@@ -0,0 +1,42 @@
+# This workflow will install Python dependencies and run tests with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Build docs
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9"]
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements_dev.txt
+    - name: Install Surprise
+      run: |
+        python -m pip install -e .
+    - name: Build docs
+      run: |
+        cd doc
+        make clean
+        make html
+    - uses: actions/upload-artifact@v3
+      with:
+        name: my-artifact
+        path: doc/build/html

README.md

@@ -173,8 +173,10 @@ License and reference
 
 This project is licensed under the [BSD
 3-Clause](https://opensource.org/licenses/BSD-3-Clause) license, so it can be
-used for pretty much everything, including commercial applications. Please let
-us know how [Surprise](http://surpriselib.com) is useful to you!
+used for pretty much everything, including commercial applications.
+
+I'd love to know how Surprise is useful to you. Please don't hesitate to open
+an issue and describe how you use it!
 
 Please make sure to cite the
 [paper](https://joss.theoj.org/papers/10.21105/joss.02174) if you use
@@ -211,9 +213,11 @@ Thanks a lot :) !
 Development Status
 ------------------
 
-Starting from version 1.1.0 (September 19), we will only maintain the
-package and provide bugfixes. No new features will be considered.
+Starting from version 1.1.0 (September 19), I will only maintain the package,
+provide bugfixes, and perhaps sometimes perf improvements. I have less time to
+dedicate to it now, so I'm unabe to consider new features.
 
-For bugs, issues or questions about [Surprise](http://surpriselib.com),
-please use the GitHub [project page](https://github.com/NicolasHug/Surprise).
-Please don't send emails (we will not answer).
+For bugs, issues or questions about [Surprise](http://surpriselib.com), please
+avoid sending me emails; I will most likely not be able to answer). Please use
+the GitHub [project page](https://github.com/NicolasHug/Surprise) instead, so
+that others can also benefit from it.

doc/source/FAQ.rst

@@ -18,7 +18,7 @@ top-10 prediction for each user.
 .. literalinclude:: ../../examples/top_n_recommendations.py
     :caption: From file ``examples/top_n_recommendations.py``
     :name: top_n_recommendations.py
-    :lines: 10-
+    :lines: 8-
 
 .. _precision_recall_at_k:
 
@@ -42,7 +42,7 @@ As a convention, we set their values to 0 in such cases.
 .. literalinclude:: ../../examples/precision_recall_at_k.py
     :caption: From file ``examples/precision_recall_at_k.py``
     :name: precision_recall_at_k.py
-    :lines: 7-
+    :lines: 5-
 
 .. _get_k_nearest_neighbors:
 
@@ -80,7 +80,7 @@ down to the use of :meth:`get_neighbors()
 .. literalinclude:: ../../examples/k_nearest_neighbors.py
     :caption: From file ``examples/k_nearest_neighbors.py``
     :name: k_nearest_neighbors.py
-    :lines: 10-
+    :lines: 9-
 
 Naturally, the same can be done for users with minor modifications.
 
@@ -97,7 +97,7 @@ serialized. It is then reloaded and can be used again for making predictions:
 .. literalinclude:: ../../examples/serialize_algorithm.py
     :caption: From file ``examples/serialize_algorithm.py``
     :name: serialize_algorithm.py
-    :lines: 9-
+    :lines: 7-
 
 .. _further_analysis:
 
@@ -169,7 +169,7 @@ with the :meth:`test()
 .. literalinclude:: ../../examples/evaluate_on_trainset.py
     :caption: From file ``examples/evaluate_on_trainset.py``
     :name: evaluate_on_trainset.py
-    :lines: 9-25
+    :lines: 7-21
 
 Check out the example file for more usage examples.
 
@@ -187,7 +187,7 @@ done as follows:
 .. literalinclude:: ../../examples/split_data_for_unbiased_estimation.py
     :caption: From file ``examples/split_data_for_unbiased_estimation.py``
     :name: split_data_for_unbiased_estimation.py
-    :lines: 10-
+    :lines: 8-
 
 How to have reproducible experiments
 ------------------------------------

doc/source/building_custom_algo.rst

@@ -21,7 +21,7 @@ in an **inner** user id, an **inner** item id (see :ref:`this note
 .. literalinclude:: ../../examples/building_custom_algorithms/most_basic_algorithm.py
     :caption: From file ``examples/building_custom_algorithms/most_basic_algorithm.py``
     :name: most_basic_algorithm.py
-    :lines: 9-
+    :lines: 7-
 
 This algorithm is the dumbest we could have thought of: it just predicts a
 rating of 3, regardless of users and items.
@@ -31,8 +31,10 @@ return a dictionary with given details: ::
 
     def estimate(self, u, i):
 
-        details = {'info1' : 'That was',
-                   'info2' : 'easy stuff :)'}
+        details = {
+            'info1' : 'That was',
+            'info2' : 'easy stuff :)'
+        }
         return 3, details
 
 This dictionary will be stored in the :class:`prediction
@@ -52,7 +54,7 @@ be done by defining the ``fit`` method:
 .. literalinclude:: ../../examples/building_custom_algorithms/most_basic_algorithm2.py
     :caption: From file ``examples/building_custom_algorithms/most_basic_algorithm2.py``
     :name: most_basic_algorithm2.py
-    :lines: 16-37
+    :lines: 13-32
 
 
 The ``fit`` method is called e.g. by the :func:`cross_validate
@@ -82,7 +84,7 @@ rating for the item:
 .. literalinclude:: ../../examples/building_custom_algorithms/mean_rating_user_item.py
     :caption: From file ``examples/building_custom_algorithms/mean_rating_user_item.py``
     :name: mean_rating_user_item.py
-    :lines: 23-35
+    :lines: 19-31
 
 Note that it would have been a better idea to compute all the user means in the
 ``fit`` method, thus avoiding the same computations multiple times.
@@ -125,7 +127,7 @@ be called in the ``fit`` method (or anywhere else).
 .. literalinclude:: ../../examples/building_custom_algorithms/with_baselines_or_sim.py
     :caption: From file ``examples/building_custom_algorithms/.with_baselines_or_sim.py``
     :name: with_baselines_or_sim.py
-    :lines: 15-47
+    :lines: 11-43
 
 
 Feel free to explore the prediction_algorithms package `source

doc/source/conf.py

@@ -78,7 +78,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

doc/source/getting_started.rst

@@ -20,7 +20,7 @@ run a cross-validation procedure:
 .. literalinclude:: ../../examples/basic_usage.py
     :caption: From file ``examples/basic_usage.py``
     :name: basic_usage.py
-    :lines: 9-
+    :lines: 7-
 
 The result should be as follows (actual values may vary due to randomization):
 
@@ -69,7 +69,7 @@ return the predictions made from the testset:
 .. literalinclude:: ../../examples/train_test_split.py
     :caption: From file ``examples/train_test_split.py``
     :name: train_test_split.py
-    :lines: 8-
+    :lines: 6-
 
 Result:
 
@@ -102,7 +102,7 @@ build a :class:`trainset <surprise.Trainset>` object:
 .. literalinclude:: ../../examples/predict_ratings.py
     :caption: From file ``examples/predict_ratings.py``
     :name: predict_ratings.py
-    :lines: 9-20
+    :lines: 7-17
 
 We can now predict ratings by directly calling the :meth:`predict()
 <surprise.prediction_algorithms.algo_base.AlgoBase.predict>` method.  Let's say
@@ -112,7 +112,7 @@ trainset!), and you know that the true rating :math:`r_{ui} = 4`:
 .. literalinclude:: ../../examples/predict_ratings.py
     :caption: From file ``examples/predict_ratings.py``
     :name: predict_ratings2.py
-    :lines: 23-27
+    :lines: 20-24
 
 The result should be:
 
@@ -152,7 +152,7 @@ dataframe.
   .. literalinclude:: ../../examples/load_custom_dataset.py
       :caption: From file ``examples/load_custom_dataset.py``
       :name: load_custom_dataset.py
-      :lines: 12-28
+      :lines: 8-24
 
   For more details about readers and how to use them, see the :class:`Reader
   class <surprise.reader.Reader>` documentation.
@@ -175,7 +175,7 @@ dataframe.
   .. literalinclude:: ../../examples/load_from_dataframe.py
       :caption: From file ``examples/load_from_dataframe.py``
       :name: load_dom_dataframe.py
-      :lines: 8-29
+      :lines: 6-27
 
   The dataframe initially looks like this:
 
@@ -206,7 +206,7 @@ cross-validation procedure with 3 splits:
 .. literalinclude:: ../../examples/use_cross_validation_iterators.py
     :caption: From file ``examples/use_cross_validation_iterators.py``
     :name: use_cross_validation_iterators.py
-    :lines: 8-
+    :lines: 6-
 
 Result could be, e.g.:
 
@@ -233,7 +233,7 @@ object:
 .. literalinclude:: ../../examples/load_custom_dataset_predefined_folds.py
     :caption: From file ``examples/load_custom_dataset_predefined_folds.py``
     :name: load_custom_dataset_predefined_folds.py
-    :lines: 13-
+    :lines: 9-
 
 Of course, nothing prevents you from only loading a single file for training
 and a single file for testing. However, the ``folds_files`` parameter still
@@ -263,7 +263,7 @@ Here is an example where we try different values for parameters ``n_epochs``,
 .. literalinclude:: ../../examples/grid_search_usage.py
     :caption: From file ``examples/grid_search_usage.py``
     :name: grid_search_usage.py
-    :lines: 9-26
+    :lines: 7-22
 
 Result:
 
@@ -283,7 +283,7 @@ please:
 .. literalinclude:: ../../examples/grid_search_usage.py
     :caption: From file ``examples/grid_search_usage.py``
     :name: grid_search_usage2.py
-    :lines: 28-30
+    :lines: 24-26
 
 .. _grid_search_note:
 .. note::
@@ -293,24 +293,32 @@ please:
 
     .. parsed-literal::
 
-        param_grid = {'k': [10, 20],
-                      'sim_options': {'name': ['msd', 'cosine'],
-                                      'min_support': [1, 5],
-                                      'user_based': [False]}
-                      }
+        param_grid = {
+            'k': [10, 20],
+            'sim_options': {
+                'name': ['msd', 'cosine'],
+                'min_support': [1, 5],
+                'user_based': [False],
+            },
+        }
 
     Naturally, both can be combined, for example for the
     :class:`KNNBaseline <surprise.prediction_algorithms.knns.KNNBaseline>`
     algorithm:
 
     .. parsed-literal::
-        param_grid = {'bsl_options': {'method': ['als', 'sgd'],
-                                      'reg': [1, 2]},
-                      'k': [2, 3],
-                      'sim_options': {'name': ['msd', 'cosine'],
-                                      'min_support': [1, 5],
-                                      'user_based': [False]}
-                      }
+        param_grid = {
+            'bsl_options': {
+                'method': ['als', 'sgd'],
+                'reg': [1, 2],
+            },
+            'k': [2, 3],
+            'sim_options': {
+                'name': ['msd', 'cosine'],
+                'min_support': [1, 5],
+                'user_based': [False],
+            },
+        }
 
 .. _cv_results_example:
 
@@ -320,7 +328,7 @@ information and can be imported in a pandas dataframe:
 .. literalinclude:: ../../examples/grid_search_usage.py
     :caption: From file ``examples/grid_search_usage.py``
     :name: grid_search_usage3.py
-    :lines: 33
+    :lines: 30
 
 In our example, the ``cv_results`` attribute looks like this (floats are
 formatted):

doc/source/index.rst

@@ -18,11 +18,6 @@ tutorials illustrating all you can do with  `Surprise
 use-case example. For installation guidelines, please refer to the `project
 page <http://surpriselib.com>`_.
 
-Any kind of feedback/criticism would be greatly appreciated (software design,
-documentation, improvement ideas, spelling mistakes, etc...). Please feel free
-to contribute and send pull requests (see `GitHub page
-<https://github.com/NicolasHug/Surprise>`_)!
-
 
 .. toctree::
    :caption: User Guide