webarkit / webarkit/webarkit.github.io

Host API documentation for WebARKit libraries (jsfeatNext first) on webarkit.org

Open
#49 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
12
Forks
2
PR merge metrics
No merged PRs in 30d

Description

Summary

Decide and set up a hosting strategy for API documentation of the WebARKit org's repositories, integrated with www.webarkit.org — starting with jsfeatNext, whose full API docs are now generatable.

Context

  • jsfeatNext now has complete TSDoc coverage across its API and a TypeDoc setup: npm run docs generates a full static HTML site (86 pages) into docs/api/ (see webarkit/jsfeatNext#71).
  • The generated output is deliberately gitignored and not published anywhere yet.
  • Publishing via the repo's own GitHub Pages was ruled out: the org's web presence is www.webarkit.org (served from this repository), so docs should live under/next to it rather than on scattered per-repo pages.
  • Other WebARKit repos (webarkit core, jsartoolkitNFT, etc.) will want the same treatment, so this should be a single org-wide pattern, not a per-repo improvisation.

Options to evaluate

  1. Subpaths on this site — e.g. webarkit.org/docs/jsfeat-next/, webarkit.org/docs/<repo>/: each library repo has a CI job that builds its docs and pushes them into this repository (or uploads an artifact this repo's build consumes).
  2. Docs subdomain — e.g. docs.webarkit.org, a dedicated docs site (could still be GitHub Pages under the hood, on a separate repo/branch) aggregating all libraries.
  3. Per-repo gh-pages + central index — each repo publishes its own docs on gh-pages; www.webarkit.org just links to them (least integration, least central control).

Considerations

  • Versioning: publish docs per release tag (e.g. /docs/jsfeat-next/0.7.6/ + latest) or only latest?
  • Automation: jsfeatNext is about to get a tag-triggered release workflow (webarkit/jsfeatNext#61) — a docs-publish step would slot naturally into it.
  • Consistency: TypeDoc for the TypeScript repos; other tooling may be needed for the C/C++/emscripten repos.

Acceptance criteria

  • A documented decision on where org API docs live and how repos publish to it
  • jsfeatNext docs published there as the pilot

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with jsfeatNext's npm run docs command and generated docs/api/ output, then review the three hosting options and the planned tag-triggered release workflow. Compare versioning, automation, and consistency across the WebARKit repositories. Done means documenting one hosting and publishing decision and publishing jsfeatNext as the pilot.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, github-actions, typescript
Domain
ci-cd, documentation, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.