Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Docs] New documentation site with vitepress #2965

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

distefanodevinj
Copy link
Collaborator

@distefanodevinj distefanodevinj commented Jan 30, 2025

Currently we use gitbook for documentation, which hosts the website and syncs to this repository for changes.

A couple problems with this current approach:

  1. While gitbook offers free hosting and two-way syncing between their editor, full access, styling, and other configuration locked behind a login. Passing around a login for docs whose source of truth is in the repository isn't ideal.
  2. We have far less control of the style of our content, no space for other static content like blogs, images, etc. Images and videos are hosted off this repository
  3. No error logs when programmatically syncing pages. Pull requests pass tests, but the pages can fail to render without warnings or errors

Trying out the static site vitepress at the recommendation of @ilyabo -- so far seems to be extremely easy to set up, customize, and publish content to.

I won't be writing new docs in this PR and will instead focus on a migration and very basic restructure (seperating developer docs & kepler user guides. Maybe one more area for contribution gudies? Not sure, will seek some advice)


  • Create developer and user guide sections
  • Structure content accordingly
  • Configure sidebar and ToC
  • Download images, redirect to static location
  • Create Styling/CSS (refer to any style guides for kepler, if they exist)
  • Assess netlify hosting & deployment
  • Write contribution and styling guides

Signed-off-by: distefanodevinj <[email protected]>
@distefanodevinj distefanodevinj marked this pull request as draft January 30, 2025 06:04
@ibgreen
Copy link
Collaborator

ibgreen commented Jan 30, 2025

Some thoughts on the tooling change...

Kepler's doc setup has felt dated and I have avoided touching the docs for quite a while so an overhaul is welcome.

As someone who moves between frameworks helping out with docs everywhere a proliferation of setups does generate a lot of friction. These website generator setups do require maintenance and it can require a fair bit of googling and experimentation to resolve breakages and issues.

FWIW, we already use docusaurus (packaged in a maintained common module) for all the openvis frameworks.

In addition we have a custom React app for the open visualization site. So even after this change, kepler will remain an outlier.

Alignment is not always practical / the right choice but worth mentioning.

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