search

apple / coremltools

Core ML tools contain supporting tools for Core ML model conversion, editing, and validation.
https://coremltools.readme.io
BSD 3-Clause "New" or "Revised" License
4.44k stars 643 forks source link

Generate HTML after 8.0 release to reflect the latest changes. #2343

Closed junpeiz closed 2 months ago

junpeiz commented 2 months ago

Preview: https://junpeiz.github.io/coremltools/docs-guides/index.html

This PR only changes the docs-guides.

Notice that it was generated useing the latest Sphinx and theme lib, which results in a lot of file changes. The generated content style is almost the same as the current docs-guides, but with some tiny improvements. Some small examples I observed:

cpompeo commented 2 months ago

Thank you so much for this @junpeiz ! Would you be willing to describe the exact steps you took to get these files to generate? I was running into some issues

junpeiz commented 2 months ago

Thank you so much for this @junpeiz ! Would you be willing to describe the exact steps you took to get these files to generate? I was running into some issues

@cpompeo Sure! Here are the steps:

  1. Make sure all libs are up-to-date by pip install -U <LIB_NAME>, and update other libs accordingly when you see the pip complains about dependency version incompatibility. Based on my experience, I need to update sphinx, sphinx-rtd-theme, docutils, readme-renderer.
  2. In main branch, run make html in docs-guides folder, and copy the result _build/html folder to a temporary location (I used ~/Download/html)
  3. Switch to gh-pages branch and create a new branch based on it (I used gh-pages-8.0-release here).
  4. Copy all files to the docs-guides directory by cp -r ~/Downloads/html/* ./docs-guides/.
  5. Git add, commit, and then create the PR.
  6. Set your forked repo's GitHub page (for my case it's https://github.com/junpeiz/coremltools/settings/pages) to use the branch (gh-pages-8.0-release here) so you can preview those pages.
aseemw commented 2 months ago

Preview: https://junpeiz.github.io/coremltools/docs-guides/index.html

This PR only changes the docs-guides.

Notice that it was generated useing the latest Sphinx and theme lib, which results in a lot of file changes. The generated content style is almost the same as the current docs-guides, but with some tiny improvements. Some small examples I observed:

  • the search box is on the left side.
  • the Contents now has a space with the icon:
image
  • After expanding the list, now the arrow will change the direction which means "collapse":
image
  • Tables have light and deep background colors in-turn, which visually help to distinguish rows in the table:
image
  • There is slightly more space between the image and its caption, which makes it less crowded:
image

Should we update the sphinx / theme versions in doc requirements so that future generations of the doc doesn't regress?

junpeiz commented 2 months ago

Should we update the sphinx / theme versions in doc requirements so that future generations of the doc doesn't regress?

Agree. Will create a PR for it.