Skip to content

[Docs] New documentation site with vitepress - #2965

Draft
distefanodevinj wants to merge 1 commit into
masterfrom
docs-vitepress-init
Draft

[Docs] New documentation site with vitepress#2965
distefanodevinj wants to merge 1 commit into
masterfrom
docs-vitepress-init

Conversation

@distefanodevinj

@distefanodevinj distefanodevinj commented Jan 30, 2025

Copy link
Copy Markdown
Collaborator

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 <ddistefano@foursquare.com>
@distefanodevinj
distefanodevinj marked this pull request as draft January 30, 2025 06:04
@ibgreen

ibgreen commented Jan 30, 2025

Copy link
Copy Markdown
Collaborator

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.

@heshan0131

Copy link
Copy Markdown
Contributor

The Gitbook was setup a long time ago, and I don't have access to it anymore. I think it's time to move a maintained solution. I am open to any suggestions. Most of the heavy lifting is to update the build script to generate markdowns based on the typescript code, which I can look into. I prefer a minimalist setup to host these markdowns, and ideally as little change as possible

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation only changes and request investigation needed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants