automerge / automerge/automerge.github.io

Automerge-C API Docs

Open
#5 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
12
Forks
12
Avg merge
1d 12h
Merged PRs (30d)
4

Description

I was talking to @jkankiewicz about getting the generated [Automerge-C](https://github.com/automerge/automerge/tree/main/rust/automerge-c) docs hosted and linked from the site.

To build the docs:
```
cmake -E make_directory automerge-c/build
cmake -S automerge-c -B automerge-c/build
cmake --build automerge-c/build --target automerge_docs
cmake -E copy_directory automerge-c/build/docs/html /automerge-c
```

The docs end up at `/automerge-c/index.html`

They're versioned along with the rest of the repo, so adding a step to generate and upload (to gh-pages) these docs as part of the JS or rust release workflow perhaps makes sense. (Will need to talk to @alexjg about this.) Worth noting — the JS docs are hosted on GH Pages, but I think the rust docs are hosted elsewhere, so we might *need* to build them as part of the JS release process (because all GH Pages stuff seemingly needs to be uploaded together).

Here's a sketch GPT generated:

```
publish-js-docs:
runs-on: ubuntu-latest
if: "!github.event.release.prerelease"
defaults:
run:
working-directory: ./javascript
steps:
- uses: actions/checkout@v5
- uses: actions/setup-node@v5
with:
node-version: "20.x"
registry-url: "https://registry.npmjs.org"
- name: Install wasm-bindgen-cli
run: cargo install wasm-bindgen-cli wasm-opt
- name: Install wasm32 target
working-directory: rust
run: rustup target add wasm32-unknown-unknown
- name: yarn install
run: yarn install
- name: build js
run: node ./scripts/build.mjs
- name: build js docs
run: npx typedoc --out api-docs/js

# 👇 Added C docs build
- name: Set up CMake
uses: jwlawson/actions-setup-cmake@v2

- name: Build C docs
run: |
cmake -E make_directory automerge-c/build
cmake -S automerge-c -B automerge-c/build
cmake --build automerge-c/build --target automerge_docs
mkdir -p api-docs/c
cp -r automerge-c/build/docs/* api-docs/c || true

- name: Deploy 🚀
uses: JamesIves/github-pages-deploy-action@v4
with:
branch: gh-pages
folder: ./javascript/api-docs
target-folder: api-docs
```

Which should put the docs here:

* `/api-docs/js/` → JS docs
* `/api-docs/c/` → C docs

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating the existing JavaScript or Rust release workflow and its GitHub Pages deployment, then inspect the automerge-c directory and the automerge_docs CMake target. Confirm where generated files should be published and how the existing JS and Rust docs are handled. Done means the C API index.html is generated during the appropriate release and linked from the website.

Written by the indexing model from the issue text.

Assessment

Tech stack
c, cmake, github-actions, javascript
Domain
ci-cd, documentation, release
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.