Skip to content

[Doc] Add docs index page#4

Merged
peytondmurray merged 1 commit intodocs-build-system-upgradefrom
docs-build-system-upgrade-index
Nov 16, 2023
Merged

[Doc] Add docs index page#4
peytondmurray merged 1 commit intodocs-build-system-upgradefrom
docs-build-system-upgrade-index

Conversation

@peytondmurray
Copy link
Copy Markdown
Owner

@peytondmurray peytondmurray commented Nov 14, 2023

Why are these changes needed?

This PR modifies the index page. It's one of the most complicated pages, and was therefore affected more than most by the upgrade. I've broken the page up into logical pieces to make it easier to maintain.

Note: For some reason git thinks I've renamed files when really the contents are totally different 🤷

  • Previously we were using markdown for the index page, but the entire page was wrapped in a raw html block. Instead of this I've created an index.rst containing the top-level toctree for the docs. A separate splash.html page containing the main content is included via a raw html directive.
  • Styles for the page are stored in splash.css and inserted into the layout with the html-page-context event during the sphinx build for this page only. The same mechanism is used to insert splash.js for handling the "Scaling With Ray" widget user interaction and code highlighting:

image

  • Certain styles have been adjusted to avoid bad color combinations with dark/light theme
  • The video iframe now expands to fill its parent div, rather than overflowing
  • The secondary (right hand) sidebar is skipped at build time on this page

Related issue number

Partially addresses ray-project#37944.
Depends on #2.
PR 3/x targeting ray-project#41115.

Checks

  • I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
  • I've run scripts/format.sh to lint the changes in this PR.
  • I've included any doc changes needed for https://docs.ray.io/en/master/.
    • I've added any new APIs to the API Reference. For example, if I added a
      method in Tune, I've added it in doc/source/tune/api/ under the
      corresponding .rst file.
  • I've made sure the tests are passing. Note that there might be a few flaky tests, see the recent failures at https://flakey-tests.ray.io/
  • Testing Strategy
    • Unit tests
    • Release tests
    • This PR is not tested :(

Signed-off-by: pdmurray <peynmurray@gmail.com>
Copy link
Copy Markdown

@maxpumperla maxpumperla left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

great, straightforward enough. Splitting up the CSS is a very good idea.

@peytondmurray peytondmurray merged this pull request into docs-build-system-upgrade Nov 16, 2023
@peytondmurray peytondmurray deleted the docs-build-system-upgrade-index branch November 16, 2023 18:50
peytondmurray pushed a commit that referenced this pull request Jan 10, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants