Challenges faced + Recommendations to Upgrade Jupyterbooks

[balajialg]

Challenges using the tool:
Migration from Jekyll to Sphinx-based Parser:

• Script for upgrading to new toc from old toc did not work. Jekyll to Sphinx-based parsing threw errors when I tried to run the below script.
  jupyter-book toc migrate _toc.yml -o _toc.yml
• Error messages received when empty files are present in a directory were not intuitive to debug. Debugging this issue was painful and time-consuming as there was no relevant documentation to figure out this issue independently.
• Files that should get removed in the documentary structure for the old parser did not get mentioned explicitly. Require more documentation
• HTML Formatting while migrating to the new parser ignored commands in the _config.yml. It would be valuable to add pointers about customizing CSS/removing such commands in the config file

Deploying the web page through gh-actions:

• Need detailed documentation on leveraging Github actions to deploy the gh-pages build. I was confused about whether I made mistakes with my config file when the files were not updated.

Recommendations:

• More fine-tuned error messages will be a tremendous value add. Highlighting five common error messages due to user mistakes and highlighting how to fix that would be immensely valuable.
• From a support process perspective, it will be valuable to figure out how to support real-time debugging for Jupyter-books? It is time-consuming to go back and forth over GitHub issues in general.