Revamp Documentation (#541)

* updated sphinx version and theme * WIP * Updated docs * Updated index * wip * Updated quickstart docs * WIP * WIP * Added different sections * Changes to indexes * added example to index * Update requirements.txt * WIP * WIP * WIP * WIP * Updated researcher doc * WIP * Update index.rst * Should work with other versions, just that we don't build wheels * Update quickstart guide * Update developer guide * Update researcher guide * Update developer guide * fixed step numbering * add announcement to docs * Updated styling * separate announcement from conf file * Styling changes * Updated install guide * Update docs * remove pypi from docs * Updated foodrecce example * Updated guides and index * update api reference * Update install * Update docs * clean up * Change api and contributors guide order * shortened official site label * Updated developer guide * Lightened dark primary color * Added tutorials, examples links to github repo * clean up * clean up * clean up * Remove duplicate index * re-organize hyperopt * minor changes * update install from github source * revise quickstart * update install from source * revise developer guide * minor changes * revise researcher guide * minor changes * revise foodrecce example * minor changes * Add link to GitHub --------- Co-authored-by: tqtg <tuantq.vnu@gmail.com>
PreferredAI · Nov 20, 2023 · 8a28d75 · 8a28d75
1 parent 1eadb83
commit 8a28d75
Show file tree

Hide file tree

Showing 34 changed files with 3,253 additions and 237 deletions.
diff --git a/README.md b/README.md
@@ -36,7 +36,7 @@
 
 Currently, we are supporting Python 3. There are several ways to install Cornac:
 
-- **From PyPI (you may need a C++ compiler):**
+- **From PyPI (recommended):**
   ```bash
   pip3 install cornac
   ```
@@ -48,10 +48,7 @@ Currently, we are supporting Python 3. There are several ways to install Cornac:
 
 - **From the GitHub source (for latest updates):**
   ```bash
-  pip3 install Cython numpy scipy
-  git clone https://github.com/PreferredAI/cornac.git
-  cd cornac
-  python3 setup.py install
+  pip3 install git+https://github.com/PreferredAI/cornac.git
   ```
 
 **Note:** 

diff --git a/docs/Makefile b/docs/Makefile
@@ -1,10 +1,10 @@
 # Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
+# You can set these variables from the command line, and also
+# from the environment for the first two.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = Cornac
 SOURCEDIR     = source
 BUILDDIR      = build
 
@@ -17,4 +17,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/announcement.html b/docs/announcement.html
@@ -0,0 +1,4 @@
+<div>
+    Welcome to our new documentation site! Please report any issues 
+    <a href='https://github.com/PreferredAI/cornac/issues/new?title=%5BDOCS%5D'>here</a>.
+</div>
diff --git a/docs/make.bat b/docs/make.bat
@@ -7,11 +7,8 @@ REM Command file for Sphinx documentation
 if "%SPHINXBUILD%" == "" (
 	set SPHINXBUILD=sphinx-build
 )
-set SOURCEDIR=source
-set BUILDDIR=build
-set SPHINXPROJ=Cornac
-
-if "%1" == "" goto help
+set SOURCEDIR=.
+set BUILDDIR=_build
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -22,15 +19,17 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
 popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,4 +1,4 @@
 Cython>=3.0.5
 numpy>=1.26.1
 scipy>=1.11.3
-sphinx-rtd-theme>=1.3.0
+pydata-sphinx-theme>=0.14.1
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -0,0 +1,24 @@
+html[data-theme="light"] {
+    --pst-color-primary: #A3361F;
+    --pst-color-secondary: #BE181E;
+    --pst-color-primary-bg: #95736d;
+    --pst-color-secondary-bg: #94dfff;
+    --pst-color-inline-code-links: #1F70A3;
+}
+
+html[data-theme="dark"] {
+    --pst-color-primary: #c15f63;
+    --pst-color-secondary: #18BEB8;
+    --pst-color-primary-bg: #95736d;
+    --pst-color-secondary-bg: #0082ba;
+    --pst-color-inline-code-links: #c4c8ff;
+}
+
+html {
+    --pst-font-size-h1: 2.5rem;
+    --pst-font-size-h2: 1.8rem;
+    --pst-font-size-h3: 1.3rem;
+    --pst-font-size-h4: 1.2rem;
+    --pst-font-size-h5: 1.1rem;
+    --pst-font-size-h6: 1.05rem;
+}
diff --git a/docs/source/_static/logo.png b/docs/source/_static/logo.png
diff --git a/docs/source/_static/switcher.json b/docs/source/_static/switcher.json
@@ -0,0 +1,7 @@
+[
+    {
+        "name": "dev",
+        "version": "1.17",
+        "url": "https://cornac.readthedocs.io/1.17/"
+    }
+]
diff --git a/docs/source/data.rst → docs/source/api_ref/data.rst b/docs/source/data.rst → docs/source/api_ref/data.rst
@@ -1,9 +1,6 @@
 Data
 ====
 
-
-.. automodule:: cornac.data
-    :members:
 
 Dataset
 ------------------------------------

diff --git a/docs/source/datasets.rst → docs/source/api_ref/datasets.rst b/docs/source/datasets.rst → docs/source/api_ref/datasets.rst
@@ -6,52 +6,52 @@ Built-in Datasets
     :members:
 
 Amazon Clothing
------------------------------------------------
+---------------
 .. automodule:: cornac.datasets.amazon_clothing
    :members:
 
 Amazon Digital Music
------------------------------------------------
+--------------------
 .. automodule:: cornac.datasets.amazon_digital_music
    :members:
 
 Amazon Office
----------------------------------------------
+-------------
 .. automodule:: cornac.datasets.amazon_office
    :members:
 
 Amazon Toys and Games
----------------------------------------------
+---------------------
 .. automodule:: cornac.datasets.amazon_toy
    :members:
 
 CiteULike
------------------------------------------
+---------
 .. automodule:: cornac.datasets.citeulike
    :members:
 
 Epinions
------------------------------------------
+--------
 .. automodule:: cornac.datasets.epinions
    :members:
 
 FilmTrust
----------------------------------------------
+---------
 .. automodule:: cornac.datasets.filmtrust
    :members:
 
 MovieLens
------------------------------------------
+---------
 .. automodule:: cornac.datasets.movielens
    :members:
 
 Netflix
----------------------------------------
+-------
 .. automodule:: cornac.datasets.netflix
    :members:
 
 Tradesy
----------------------------------------
+-------
 .. automodule:: cornac.datasets.tradesy
    :members:
 
diff --git a/docs/source/eval_methods.rst → docs/source/api_ref/eval_methods.rst b/docs/source/eval_methods.rst → docs/source/api_ref/eval_methods.rst
@@ -1,29 +1,29 @@
 Evaluation Methods
-======================
+==================
 
 .. automodule:: cornac.eval_methods
 
 Base Method
------------------------------------------------
+-----------
 .. automodule:: cornac.eval_methods.base_method
    :members:
 
 Cross Validation
-----------------------------------------------------
+----------------
 .. automodule:: cornac.eval_methods.cross_validation
    :members:
 
 Propensity Stratified Evaluation
---------------------------------------------------------------------
+--------------------------------
 .. automodule:: cornac.eval_methods.propensity_stratified_evaluation
    :members:
 
 Ratio Split
------------------------------------------------
+-----------
 .. automodule:: cornac.eval_methods.ratio_split
    :members:
 
 Stratified Split
-----------------------------------------------------
+----------------
 .. automodule:: cornac.eval_methods.stratified_split
-   :members:
+   :members:
diff --git a/docs/source/experiment.rst → docs/source/api_ref/experiment.rst b/docs/source/experiment.rst → docs/source/api_ref/experiment.rst
@@ -4,26 +4,26 @@ Experiment
 .. automodule:: cornac.experiment
 
 Experiment
---------------------------------------------
+----------
 .. automodule:: cornac.experiment.experiment
    :members:
 
 Result
-----------------------------------------
+------
 .. automodule:: cornac.experiment.result
    :members: Result
 
 CVResult
-----------------------------------------
+--------
 .. automodule:: cornac.experiment.result
    :members: CVResult
 
 ExperimentResult
-----------------------------------------
+----------------
 .. automodule:: cornac.experiment.result
    :members: ExperimentResult
 
 CVExperimentResult
-----------------------------------------
+------------------
 .. automodule:: cornac.experiment.result
    :members: CVExperimentResult
diff --git a/docs/source/api_ref/hyperopt.rst b/docs/source/api_ref/hyperopt.rst
@@ -0,0 +1,18 @@
+Hyper-parameter Tuning
+======================
+
+
+Grid Search
+---------------
+.. automodule:: cornac.hyperopt
+   :members: GridSearch
+
+Random Search
+--------------------
+.. automodule:: cornac.hyperopt
+   :members: RandomSearch
+
+Search Domain
+---------------
+.. automodule:: cornac.hyperopt
+   :members: Discrete, Continuous
diff --git a/docs/source/api_ref/index.rst b/docs/source/api_ref/index.rst
@@ -0,0 +1,17 @@
+API Reference
+=============
+
+Welcome to the API Reference. This section contains the documentation of the
+functions and classes of the ``cornac`` package.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference
+
+   data
+   models
+   metrics
+   eval_methods
+   experiment
+   datasets
+   hyperopt
diff --git a/docs/source/metrics.rst → docs/source/api_ref/metrics.rst b/docs/source/metrics.rst → docs/source/api_ref/metrics.rst
@@ -8,15 +8,15 @@ Rating
 ++++++
 
 Mean Absolute Error (MAE)
-----------------------------
+-------------------------
 .. autoclass:: MAE
 
 Mean Squared Error (MSE)
 ------------------------
 .. autoclass:: MSE
 
 Root Mean Squared Error (RMSE)
---------------------------------
+------------------------------
 .. autoclass:: RMSE
 
 +++++++
@@ -28,29 +28,29 @@ Area Under the Curve (AUC)
 .. autoclass:: AUC
 
 Fmeasure (F1)
--------------------
+-------------
 .. autoclass:: FMeasure
 
 Mean Average Precision (MAP)
 ----------------------------
 .. autoclass:: MAP
 
 Mean Reciprocal Rank (MRR)
--------------------------------------------
+--------------------------
 .. autoclass:: MRR
 
 Normalized Cumulative Reciprocal Rank (NCRR)
 --------------------------------------------
 .. autoclass:: NCRR
 
 Normalized Discount Cumulative Gain (NDCG)
--------------------------------------------
+------------------------------------------
 .. autoclass:: NDCG
 
 Precision
--------------------
+---------
 .. autoclass:: Precision
 
 Recall
--------------------
-.. autoclass:: Recall
+------
+.. autoclass:: Recall