Skip to content

Refactor /docs into Concepts#3877

Merged
JasonAtClockwork merged 21 commits intomasterfrom
jlarabie/docs-refactor
Dec 17, 2025
Merged

Refactor /docs into Concepts#3877
JasonAtClockwork merged 21 commits intomasterfrom
jlarabie/docs-refactor

Conversation

@JasonAtClockwork
Copy link
Contributor

@JasonAtClockwork JasonAtClockwork commented Dec 12, 2025

Description of Changes

Refactoring all sections to match a concept based approach to the docs.

Closes: #3840

API and ABI breaking changes

N/A

Expected complexity level and risk

1

Testing

  • Walking through all code references before pushing

Copy link
Contributor

@gefjon gefjon left a comment

Choose a reason for hiding this comment

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

Not a thorough review yet, just a few thoughts. Structurally this looks great, thanks so much!

@JasonAtClockwork
Copy link
Contributor Author

The current TypeScript reference documentation on views seems wrong, I was mirroring this over to the new Views documentation and there seems to be several bugs. I'll reach out early next week to get assistance on this if I don't solve it myself first.

@JasonAtClockwork
Copy link
Contributor Author

@JulienLavocat - I've added you to review the work I've done here for the menu, I needed another level for the menu and I've let my CSS skills atrophy. I've targeted specifically the second level menu to get something workable for now as exampled here:
image

@JasonAtClockwork
Copy link
Contributor Author

@gefjon @cloutiertyler - I wanted to provide a write-up of the changes to hopefully make this review as targeted as possible.

  1. Refactored Getting Started into a new structure splitting up the large overview page into smaller pages with the quickstarts + tutorials alongside in the same section. (also added TypeScript where it was missing)
  2. Added Modules section with overview, creating modules, building + publishing, and a cheat sheet instead of full reference.
    a. I moved the Row Level Security, and Deploying pages into this section as well
  3. Added Databases section with overview, and moved the migrations pages, reject client connections, and SQL pages into this section
  4. Added Tables section splitting up the details into overview, columns, indexes, permissions, schedules, and performance
  5. Added Functions section with an overview, reducers into it's own expanded category, procedures, and views (the views code isn't working in TypeScript so I need to review this still)
  6. Updated Client SDK Languages to include codegen (Generating Client Bindings), connections (Connecting to SpacetimeDB), and an SDK API Overview along with the previous references
  7. To clean up the other miscellaneous pages I created a new Reference section and moved the CLI Reference, HTTP API, Internals, and Appendix in this one
  8. Old Modules we'll remove I've just left it as a reference for now until we're happy
  9. Subscriptions and Spacetime-Auth I think are okay for now but I have added a couple reference points to them in the other pages

The one thing I'm uncertain about is Modules v Databases and if it should be one section where we merge some of the details together?

@JasonAtClockwork JasonAtClockwork marked this pull request as ready for review December 16, 2025 18:57
Copy link
Contributor

@cloutiertyler cloutiertyler left a comment

Choose a reason for hiding this comment

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

I left comments inline. I think this is an excellent first pass. I think once the comments are resolved this can merge. I took a look at the styling too by running it locally. We'll want @randyclockwork to take a pass at some point, but I think this is fine for now.

I would like to take a second pass at this where we really try to distill down the basic concepts and put them together towards the top of the document. As it stands I think the table of contents is a little verbose before getting to the core concepts:

Image

I would love to see the table of contents look more like:

Intro
    Getting Started
    Quickstarts
    Tutorials
Core Concepts
    Databases # I think we modify this to include modules as a section
    Tables
    Functions
    Subscriptions
    Authentication

Where if you expand all the sections it would look like:

Intro
    Getting Started
    Quickstarts
        React
        Vue
        HTML
        Unity
        Unreal
        Godot
        Rust
        ... etc
    Tutorials
        Chat App # With language selectors for all the languages
        Blackholio (Unity)
        Blackholio (Unreal)
Core Concepts
    Databases
        The Database Module
        Developing databases
        Building and publishing
        Transactions & Atomicity # discussion about atomic transactions and what they are (could also go in Functions)
        Automatic migrations # these could also go into an "Advanced usage section"
        Incremental migrations # these could also go into an "Advanced usage section"        
    Functions
        Overview
        Reducers
        Procedures
        Views
    Tables
        Defining tables
        Reading data
        Writing data
        Scheduled tables
        Performance best practices
        Advanced
            System tables
    Subscriptions
        Subscribing to tables
        Reducer callbacks # will become event tables
        Advanced semantics # should perhaps be embedded in one of the above
    Authentication
        SpacetimeAuth
        Clerk
        Auth0
        # ... etc
Other features
        PostgreSQL compatibility   

We might at some point need deeper levels of nesting and will need UI design for that.

Also please remove the "old files" before merging.

@JasonAtClockwork JasonAtClockwork added the documentation Improvements or additions to documentation label Dec 16, 2025
JasonAtClockwork and others added 13 commits December 17, 2025 08:39
- Removal of confusing Rust/C# module note
- Added missing useReducer import
- Moved PrettyMessages below users to fix a bug later in the tutorial
- Updated PrettyMessages to have null safety if the user follows the module bindings they may have an error due to spacetime call send_message
…ture.md

Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Signed-off-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: Tyler Cloutier <cloutiertyler@users.noreply.github.com>
Signed-off-by: Jason Larabie <jason@clockworklabs.io>
@JasonAtClockwork JasonAtClockwork added this pull request to the merge queue Dec 17, 2025
@JasonAtClockwork JasonAtClockwork removed this pull request from the merge queue due to a manual request Dec 17, 2025
@JasonAtClockwork JasonAtClockwork added this pull request to the merge queue Dec 17, 2025
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Dec 17, 2025
@JasonAtClockwork JasonAtClockwork added this pull request to the merge queue Dec 17, 2025
@github-merge-queue github-merge-queue bot removed this pull request from the merge queue due to failed status checks Dec 17, 2025
@JasonAtClockwork JasonAtClockwork added this pull request to the merge queue Dec 17, 2025
Merged via the queue into master with commit e9d2b11 Dec 17, 2025
65 of 72 checks passed
github-merge-queue bot pushed a commit that referenced this pull request Dec 19, 2025
# Description of Changes

With the refactor docs I had left the original module folder and
mistakenly didn't remove it as requested as per Tyler's comment:
#3877 (review):
> Also please remove the "old files" before merging.

# API and ABI breaking changes

N/A

# Expected complexity level and risk

1

# Testing

Removal of documents there is no test to run

Co-authored-by: Zeke Foppa <196249+bfops@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

3 participants