search

recommenders-team / recommenders

Best Practices on Recommendation Systems
https://recommenders-team.github.io/recommenders/intro.html
MIT License
18.71k stars 3.06k forks source link

New documentation with Jupyter book #2051

Closed miguelgfierro closed 7 months ago

miguelgfierro commented 8 months ago

Description

Documentation with Jupyter Book. It can be found here: https://recommenders-team.github.io/recommenders

Related Issues

2016

References

Checklist:

miguelgfierro commented 8 months ago

If I add a relative path, it doesn't show in the table of contents

parts:
  - caption: Getting Started
    chapters:
      - file: ../SETUP.md
miguelgfierro commented 8 months ago

Current errors:

WARNING: autodoc: failed to import module 'cosmos_cli' from module 'recommenders.datasets'; the following exception was raised:
No module named 'pydocumentdb'
/home/u/MS/recommenders/recommenders/evaluation/spark_evaluation.py:docstring of recommenders.evaluation.spark_evaluation.SparkRatingEvaluation.rsquared:5: WARNING: Duplicate explicit target name: "here".
/home/u/MS/recommenders/recommenders/evaluation/spark_evaluation.py:docstring of recommenders.evaluation.spark_evaluation.SparkRatingEvaluation.rsquared:5: WARNING: Duplicate explicit target name: "here".
/home/u/MS/recommenders/recommenders/evaluation/spark_evaluation.py:docstring of recommenders.evaluation.spark_evaluation.SparkRatingEvaluation.rsquared:5: WARNING: Duplicate explicit target name: "here".
/home/u/MS/recommenders/recommenders/evaluation/spark_evaluation.py:docstring of recommenders.evaluation.spark_evaluation.SparkRatingEvaluation.rsquared:5: WARNING: Duplicate explicit target name: "here".
/home/u/MS/recommenders/docs/index.rst:10: WARNING: toctree directive not expected with external-toc [etoc.toctree]
/home/u/MS/recommenders/docs/intro.md:: WARNING: toctree contains reference to nonexisting document '../SETUP' [etoc.ref]
/home/u/MS/recommenders/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py:docstring of recommenders.models.deeprec.models.sequential.rnn_cell_implement.Time4ALSTMCell.call:11: ERROR: Unexpected indentation.
/home/u/MS/recommenders/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py:docstring of recommenders.models.deeprec.models.sequential.rnn_cell_implement.Time4ALSTMCell.call:13: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/u/MS/recommenders/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py:docstring of recommenders.models.deeprec.models.sequential.rnn_cell_implement.Time4ALSTMCell.call:31: ERROR: Unexpected indentation.
/home/u/MS/recommenders/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py:docstring of recommenders.models.deeprec.models.sequential.rnn_cell_implement.Time4ALSTMCell.call:32: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/u/MS/recommenders/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py:docstring of recommenders.models.deeprec.models.sequential.rnn_cell_implement.Time4LSTMCell.call:11: ERROR: Unexpected indentation.
/home/u/MS/recommenders/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py:docstring of recommenders.models.deeprec.models.sequential.rnn_cell_implement.Time4LSTMCell.call:13: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/u/MS/recommenders/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py:docstring of recommenders.models.deeprec.models.sequential.rnn_cell_implement.Time4LSTMCell.call:31: ERROR: Unexpected indentation.
/home/u/MS/recommenders/recommenders/models/deeprec/models/sequential/rnn_cell_implement.py:docstring of recommenders.models.deeprec.models.sequential.rnn_cell_implement.Time4LSTMCell.call:32: WARNING: Block quote ends without a blank line; unexpected unindent.
WARNING: autodoc: failed to import module 'geoimc_algorithm' from module 'recommenders.models.geoimc'; the following exception was raised:
No module named 'pymanopt'
/home/u/MS/recommenders/recommenders/models/newsrec/models/layers.py:docstring of recommenders.models.newsrec.models.layers.ComputeMasking.call:11: ERROR: Unexpected indentation.
/home/u/MS/recommenders/recommenders/models/newsrec/models/layers.py:docstring of recommenders.models.newsrec.models.layers.ComputeMasking.call:13: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/u/MS/recommenders/recommenders/models/newsrec/models/layers.py:docstring of recommenders.models.newsrec.models.layers.ComputeMasking.call:31: ERROR: Unexpected indentation.
/home/u/MS/recommenders/recommenders/models/newsrec/models/layers.py:docstring of recommenders.models.newsrec.models.layers.ComputeMasking.call:32: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/u/MS/recommenders/recommenders/models/newsrec/models/layers.py:docstring of recommenders.models.newsrec.models.layers.OverwriteMasking.call:11: ERROR: Unexpected indentation.
/home/u/MS/recommenders/recommenders/models/newsrec/models/layers.py:docstring of recommenders.models.newsrec.models.layers.OverwriteMasking.call:13: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/u/MS/recommenders/recommenders/models/newsrec/models/layers.py:docstring of recommenders.models.newsrec.models.layers.OverwriteMasking.call:31: ERROR: Unexpected indentation.
/home/u/MS/recommenders/recommenders/models/newsrec/models/layers.py:docstring of recommenders.models.newsrec.models.layers.OverwriteMasking.call:32: WARNING: Block quote ends without a blank line; unexpected unindent.
WARNING: autodoc: failed to import module 'RLRMCalgorithm' from module 'recommenders.models.rlrmc'; the following exception was raised:
No module named 'pymanopt'
WARNING: autodoc: failed to import module 'conjugate_gradient_ms' from module 'recommenders.models.rlrmc'; the following exception was raised:
No module named 'pymanopt'
/home/u/MS/recommenders/recommenders/models/sar/sar_singlenode.py:docstring of recommenders.models.sar.sar_singlenode.SARSingleNode.fit:3: ERROR: Content block expected for the "note" directive; none found.
/home/u/MS/recommenders/recommenders/utils/notebook_utils.py:docstring of recommenders.utils.notebook_utils.execute_notebook:3: ERROR: Content block expected for the "note" directive; none found.
/home/u/MS/recommenders/recommenders/utils/tf_utils.py:docstring of recommenders.utils.tf_utils.evaluation_log_hook:26: WARNING: Inline strong start-string without end-string.
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/u/MS/recommenders/docs/index.rst: WARNING: document isn't included in any toctree
done
miguelgfierro commented 8 months ago

The error: ERROR: Unexpected indentation. means that there is no docstring o_o

Very descriptive. Congrats!!

miguelgfierro commented 8 months ago

Error. The documentation is not rendered correctly, there are extra : image

Instead of the latest jupyter-book version, 0.15.1, I tried with 0.13.2, and sphinx-4.5.0-> that fixes the issue.

Trying with 0.15.0 and sphinx-v5.0.2 -> it doesn't fix the double : error Trying 0.14.0 and sphinx 5.0.2 -> it doesn't fix the double : error Trying 0.14.0 and sphinx 4.5.-> it doesn't build The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version. Trying with 0.15.0 and sphinx-4.5.0 -> it doesn't build The sphinxcontrib.applehelp extension used by this project needs at least Sphinx v5.0; it therefore cannot be built with this version. Trying with 0.15.0 and sphinx-5.1.0 (this combination has internal conflicts)-> it fixes the issue https://github.com/recommenders-team/recommenders/commits/f892bf018bbc3f47bff738acaefa094ecdcbdf90

Trying to compile the docs with jupyter-book config sphinx docs/ and sphinx-build docs docs/_build/html -b html. The build passes: https://github.com/recommenders-team/recommenders/actions/runs/7532474883/job/20503161028?pr=2051 -> I still get the double ::

miguelgfierro commented 8 months ago

Error when trying to push the files from the GitHub actions to the repo:

Author identity unknown

*** Please tell me who you are.

Run

  git config --global user.email "you@example.com"
  git config --global user.name "Your Name"

to set your account's default identity.
Omit --global to set the identity only in this repository.
miguelgfierro commented 7 months ago

In PyTorch, they are using sphinx directly:

agoose77 commented 7 months ago

@miguelgfierro could you try with the newest version of JB?

miguelgfierro commented 7 months ago

@agoose77 it works now https://recommenders-team.github.io/recommenders/

Thanks man!

SimonYansenZhao commented 7 months ago

.readthedocs.yaml is not used any more if we use Jupyter Book. @miguelgfierro