Skip to content

Conversation

@kvargha
Copy link
Contributor

@kvargha kvargha commented Jan 6, 2026

Problem Statement

  1. Jekyll documentation is based on Ruby, and I've found it difficult everytime I need to setup a new Ruby environment when I try to run the docs locally.
  2. UX of documentation is not intuitive and the TableOfContents is overwhelming.
  3. Jekyll doesn't have the ability to toggle between dark and light mode.
  4. Some docs are in the wrong place.

Solution

Migrating to MkDocs Material addresses 1-3.

  • Merged the doc and JavaDoc deployments into one GitHub Action.
  • Navigation and page Table Of Contents are separated for a less overwhelming page experience.
  • Header
    • The Venice lion is now in the header for better branding.
    • Link to the Venice repo and number of stars/forks are pinned at the top right.
  • Footer
    • Includes "Previous" and "Next" pages for a guided navigation experience.
    • Socials are added.

4: Moved some pages around to better locations so it's less confusing for first-time users.

New docs can be viewed here.
JavaDocs still work too.

Code changes

  • Added new code behind a config. If so list the config names and their default values in the PR description.
  • Introduced new log lines.
    • Confirmed if logs need to be rate limited to avoid excessive logging.

Concurrency-Specific Checks

Both reviewer and PR author to verify

  • Code has no race conditions or thread safety issues.
  • Proper synchronization mechanisms (e.g., synchronized, RWLock) are used where needed.
  • No blocking calls inside critical sections that could lead to deadlocks or performance degradation.
  • Verified thread-safe collections are used (e.g., ConcurrentHashMap, CopyOnWriteArrayList).
  • Validated proper exception handling in multi-threaded code to avoid silent thread termination.

How was this PR tested?

  • New unit tests added.
  • New integration tests added.
  • Modified or extended existing tests.
  • Verified backward compatibility (if applicable).

Does this PR introduce any user-facing or breaking changes?

  • No. You can skip the rest of this section.
  • Yes. Clearly explain the behavior change and its impact.
    Links for pages are changed.

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.

1 participant