[SDK] spike: find a better way of publishing docs to GitBook

Is your feature request related to a problem? Please describe.
Atm when publishing new SDK version we have to create a new branch that corresponds to version tag, create a new "doc collection" in GitBook space, then fully sync GitHub repo from the created branch to created collection and set it to latest version. This process is not only doesn't have any instruction, but also implicit by it's nature, seems to be heavy-weight and also pollutes our repository with unnecessary branches (we don't use them for overall releases, i.e. we don't checkout from these branches for hotfixes on old versions, we use just to publish docs).

Describe the solution you'd like
The expected solution should be simpler. Ideally syncing version tag and docs, but not sure it's possible, so this spike is to investigate possible solutions and then we pick one that is a good fit.

Describe alternatives you've considered
TBD by the spike engineer

Additional context
Might make sense to work on this together w/ #3424 as it's kinda related

Did some research on it. We can use an automated way by triggering Gitbook space creating via API and then importing it from git tag ref instead of a branch via API endpoint they have. It's a one-time import (i.e. just imports the content, doesn't set up bi-directional sync between GitHub & GitBook), so the sequence of steps will be:

Publish an SDK package & create a git tag for it
Trigger "gitbook" action on tag creation
In github action: create a new space in gitbook, take its id and trigger import from tag
Go to gitbook and manually write a changelog (we don't have an automated one)

@portuu3

@portuu3 wdyt on the above suggestion? This way we won't need to have tons of branches and it can be triggered either manually via Postman or we can have a GitHub action for it to create space automatically + trigger sync from git tag

@dnechay

@dnechay overall looks good to me. Just I wonder if it can be placed inside SDK.
Also with UI you cannot choose a tag as ref, we should check if it is possible via API

@portuu3

@portuu3

Just I wonder if it can be placed inside SDK

What exactly you mean? Docs folder? If so, I suppose it should be possible, because you simply provide a path to directory for GitBook, so it can be placed anywhere

Also with UI you cannot choose a tag as ref, we should check if it is possible via API

That's true it's not possible via UI, but it's possible via API: I've already done it for 4.3.0 release (you can check that we have docs, but there is no branch), the format is next (POST: https://api.gitbook.com/v1/spaces/space_id/git/import):

{
    "url": "https://github.com/humanprotocol/human-protocol",
    "ref": "refs/tags/[email protected]",
    "repoProjectDirectory": "./"
}

and include api key (generated on UI) in "bearer" auth

@dnechay

@dnechay

What exactly you mean? Docs folder? If so, I suppose it should be possible, because you simply provide a path to directory for GitBook, so it can be placed anywhere

I mean inside SDK site as new version of the docs and also set the new version as default.

@portuu3

@portuu3 from what I see in their docs - yes, it's possible to create a new site section via API with new version space assigned to it and then make this new section a default for the site (PATCH call to update site with defaultSiteSpace prop set to new section id). So github action can look like:

Triggered on new sdk@<version> tag creation
Extract <version> from tag
Create new space in GitBook, and keep the id of created space
Import docs from git tag ref to created space
Create new site section from space id, keep its id
Make new section default (home page)

@dnechay

@portuu3 from what I see in their docs - yes, it's possible to create a new site section via API with new version space assigned to it and then make this new section a default for the site (PATCH call to update site with defaultSiteSpace prop set to new section id). So github action can look like:

Triggered on new sdk@<version> tag creation

Extract <version> from tag

Create new space in GitBook, and keep the id of created space

Import docs from git tag ref to created space

Create new site section from space id, keep its id

Make new section default (home page)

@dnechay looks good to me then

Navigation Menu

Repository navigation

[SDK] spike: find a better way of publishing docs to GitBook #3483

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[SDK] spike: find a better way of publishing docs to GitBook #3483

Description

Activity

dnechay commented on Sep 2, 2025

dnechay commented on Sep 3, 2025

portuu3 commented on Sep 22, 2025

dnechay commented on Sep 22, 2025

portuu3 commented on Sep 22, 2025

dnechay commented on Sep 22, 2025

portuu3 commented on Sep 23, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions