Since the last big blocker for releasing rs.js 2.0 was the broken documentation setup for quite a while now, I embarked on a little journey last week and ended up with what I think is a pretty good improvement for both the main remoteStorage website as well as the rs.js documentation.
SphinxJS and especially its TypeDoc integration have not been properly maintained, since the project was abandoned by Mozilla. And regular changes in the ReadTheDocs build setup also required regular time investment on our part to make things work. I didnāt see a good way of fixing that situation, other than ripping out all the parts that kept breaking over time.
Then I ran into VitePress, and found out that thereās even a TypeDoc Markdown plugin for it. And since we already used Markdown for the main website, I thought why not combine all of it into one again.
So hereās what I have right now:
One nice aspect, among many benefits of this new setup, is that you can run a preview of only the rs.js documentation directly in the rs.js repo, without even checking out the website repo. And in the website repo, I added rs.js as a Git submodule, so you can either pull in rs.js docs changes or push them from there, too.
If you want to try it out for yourself, just npm install the dependencies in either repo (no --force required anymore), and then just run npm run docs:dev.
Other benefits:
Everything is Markdown now, no RST anymore (even examples in the TypeDoc comments are Markdown)
More independence from GitHub Pages tech again. We just deploy a static build and pull in the contributor list via a script before building. That also means no Jekyll/Ruby for local builds anymore.
We can cross-link locally between the main website and the rs.js docs
VitePress default theme niceties like dark mode, page content navigation/summary on the right side, etc.
We can customize anything, pull in remote data, and add more interactive features with Vue components (see e.g. the Contributors component for that). Could even add real demos directly in the docs.
Modern versions of TypeScript and TypeDoc fully supported, and we can use all their features. No dependency hell for that anymore
ā¦
Current status
Most of the work has already been done, including content updates and improvements. Left to do:
Fully port all of the rs.js docsā content
Write a new contribution doc for the documentation/website itself
Go over all pages and make sure all links are working, revise outdated content
Add content to the new Design page on the main website, get rid of the legacy wiki folder/pages
Add a GitHub Action for deploying the static build dir to GitHub pages
Resize the images on the how-it-works pages (scale via CSS)
Update image/asset handling in rs.js docs
ā¦
Hope you all like it! Would appreciate any feedback and other help I can get on this.
One thing I forgot: there is now a pretty obvious gaping hole on top of that new home page, which could be filled with a nice large graphic representation of either just the logo, or what remoteStorage is about at a glance.
Phew, I think Iām finally done porting all existing documentation, and especially all the API docs!
There are a ton of small updates and improvements I did on the way, both to the content as well as things like module and type exports/imports for example (only exported interfaces get rendered by typedoc). And the new content navigation on the right side is an absolute blessing for quickly jumping exactly to what youāre looking for.
Please have a look, and add some review comments to the rs.js PR:
After having launched the new website last year, we recently also automated the publishing of rs.js docs from the rs.js repo to the website repo/pages.
So now, when you simply edit a Markdown document of either the normal pages or the rs.js documentation pages on GitHub (either via built-in editor or locally) and then open a PR for it, anything merged to the respective master branch will be published to remotestorage.io right away.
And when you edit Typedoc comments in the rs.js codebase, those will be published to the docs pages automatically when the next remoteStorage.js release version is pushed to GitHub.
In short: it has never been easier to contribute to the remoteStorage website and reference client documentation!
In fact, we already published some important improvements to the rs.js Getting Started docs, and Iām looking forward to making them even better. Any and all feedback helps, and no improvement is too small for the āEdit this pageā link.
