Skip to content

Add MkDocs documentation site with Solid brand styling, GitHub Pages deployment, and doc example tests#31

Open
Copilot wants to merge 9 commits intomainfrom
copilot/develop-documentation-for-package
Open

Add MkDocs documentation site with Solid brand styling, GitHub Pages deployment, and doc example tests#31
Copilot wants to merge 9 commits intomainfrom
copilot/develop-documentation-for-package

Conversation

Copy link
Contributor

Copilot AI commented Mar 20, 2026

The package had no formal documentation beyond a minimal README. This adds a full MkDocs site covering all public API surface, deployed to GitHub Pages, styled with the Solid Project brand colour (Royal Lavender #7C4DFF). Documentation examples are executed as part of CI with coverage reporting, and a sync script keeps example code in the docs and tests in lock-step.

README

  • Replaced wall-of-text with scannable sections: quick example, installation, per-concept snippets
  • Links to hosted docs for full reference
  • Nested Objects snippet made self-contained (added TermWrapper import and Address stub)
  • Decorators snippet changed to typescript fence with TermWrapper import and proper types

MkDocs site (docs/)

  • Home + Getting Started — quick example, concepts table, first mapping walkthrough
  • GuidesTermWrapper, DatasetWrapper, nested objects, sets/maps, RDF lists, decorators; each with runnable examples
  • API referenceTermWrapper, DatasetWrapper, ValueMapping, TermMapping, ObjectMapping, decorators; full method signatures and parameter tables
  • API accuracy fixes: ObjectMapping.as return type corrected to IValueMapping<T> & ITermMapping<T>; getter()/setter() return types corrected to accurate decorator factory shapes; import sections updated to include all referenced symbols
  • Self-referencing decorator limitation documented in docs/api/decorators.md with a corrected Full Decorated Class Example using Friend/PersonDecorated split

Styling (docs/stylesheets/extra.css)

Overrides Material theme CSS variables to apply Royal Lavender (#7C4DFF) to the masthead, footer, and nav tabs per the Solid style guide.

CI (mkdocs.yml + .github/workflows/docs.yml + .github/workflows/ci.yml)

mkdocs-material build gated with --strict; deploys to GitHub Pages on push to main via actions/deploy-pages. A pull_request trigger runs the build-only step on PRs to catch breakage before merge.

- run: mkdocs build --strict
- uses: actions/deploy-pages@v4

npm run check-doc-examples is added as a step in the test job of .github/workflows/ci.yml, running on every push across all OS matrix targets. This ensures doc code blocks never drift from the canonical example files in test/docs/examples/.

site/ added to .gitignore.

Documentation example tests (test/docs/)

Example code is stored once in test/docs/examples/ (the single source of truth) and shared between the test suite and the documentation via a sync script — eliminating duplication and keeping both in lock-step.

test/docs/examples/ — 10 TypeScript files (single source of truth)

Each file contains only the class definition(s) with their @rdfjs/wrapper imports. These are what tests import and what docs display:

File Exports
term-wrapper.ts Book
nested-objects.ts Address, Person
sets-and-maps-article.ts Article
sets-and-maps-person.ts Person (with friends Set)
sets-and-maps-map.ts Resource
rdf-lists.ts Playlist, EX
dataset-wrapper.ts Person, People
decorators-article.ts Tag, Article
decorators-equivalence.ts ArticleManual, ArticleDecorated
decorators-person.ts Friend, PersonDecorated

test/docs/*.test.ts — 6 test files import classes from the example files and add assertions. No class body duplication.

scripts/sync-doc-examples.mjs — reads each example file and updates the matching <!-- example: STEM --><!-- /example --> slot in the doc markdown:

  • npm run sync-doc-examples — updates docs in place
  • npm run check-doc-examples — exits 1 if any doc is out of sync (enforced in CI via .github/workflows/ci.yml)

test/tsconfig.json updated to compile test/docs/ (including test/docs/examples/). A dedicated npm run test:docs script runs only the documentation tests with --experimental-test-coverage to produce a docs-specific coverage report.

Coverage impact:

  • Combined (all tests): lines 87.10% → 89.58%, functions 78.40% → 82.10%
  • Docs-only (npm run test:docs): lines 76.30%, branch 91.02%, functions 61.73%
Original prompt

Please review this package and develop documentation of how to use it; appropriately including some in the readme and the remainder in mkdocs deployed on github pages.

The styling of the mkdocs should be as defined in this skill https://github.com/solid/solid-llm-skills/blob/main/solid/style-guide.md

Created from VS Code.


🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

Copilot AI changed the title [WIP] Add documentation for package usage in README and MkDocs Add MkDocs documentation site with Solid brand styling and GitHub Pages deployment Mar 20, 2026
Copilot AI requested a review from jeswr March 20, 2026 23:26
@jeswr jeswr marked this pull request as ready for review March 21, 2026 12:22
Copilot AI review requested due to automatic review settings March 21, 2026 12:22
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Adds a full MkDocs documentation site for the RDF/JS Wrapper library (guides + API reference), applies Solid-style “Royal Lavender” branding via Material theme overrides, and introduces a GitHub Pages deployment workflow. This modernizes the project docs beyond the existing README and provides a hosted reference for the public API surface.

Changes:

  • Added MkDocs Material site configuration, navigation, and authored docs pages under docs/ (guides + API reference).
  • Added Solid brand styling via docs/stylesheets/extra.css.
  • Added GitHub Actions workflow to build/deploy docs to GitHub Pages; ignored the generated site/ output.

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 8 comments.

Show a summary per file
File Description
mkdocs.yml MkDocs Material configuration, nav, and markdown extensions.
docs/stylesheets/extra.css Solid brand color overrides for header/footer/tabs.
docs/index.md Docs homepage with quick example and positioning.
docs/getting-started.md Installation + first mapping walkthrough.
docs/guides/term-wrapper.md TermWrapper conceptual guide + examples.
docs/guides/dataset-wrapper.md DatasetWrapper conceptual guide + examples.
docs/guides/nested-objects.md ObjectMapping-based navigation guide.
docs/guides/sets-and-maps.md Live Set/Map guide + examples.
docs/guides/rdf-lists.md RDF list (ObjectMapping.asList) guide + supported ops.
docs/guides/decorators.md Decorator-based mapping guide + TS configuration note.
docs/api/term-wrapper.md TermWrapper API reference.
docs/api/dataset-wrapper.md DatasetWrapper API reference.
docs/api/value-mapping.md ValueMapping API reference.
docs/api/term-mapping.md TermMapping API reference.
docs/api/object-mapping.md ObjectMapping API reference.
docs/api/decorators.md Decorators API reference.
README.md Restructured README with links to hosted docs and updated examples.
.gitignore Ignores MkDocs output directory (site/).
.github/workflows/docs.yml Builds MkDocs with --strict and deploys to GitHub Pages.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

## ObjectMapping.as

```typescript
ObjectMapping.as<T>(constructor: ITermWrapperConstructor<T>): IValueMapping<T>
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

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

ObjectMapping.as is described as usable as both a value mapping and a term mapping, but the signature only shows IValueMapping<T>. For clarity in the API reference, consider documenting it as returning an intersection type (e.g. IValueMapping<T> & ITermMapping<T>) or otherwise explicitly noting it is structurally compatible with ITermMapping<T> as well.

Suggested change
ObjectMapping.as<T>(constructor: ITermWrapperConstructor<T>): IValueMapping<T>
ObjectMapping.as<T>(constructor: ITermWrapperConstructor<T>): IValueMapping<T> & ITermMapping<T>

Copilot uses AI. Check for mistakes.
Comment on lines +104 to +105
import { TermWrapper, ValueMapping, TermMapping } from "@rdfjs/wrapper"
import type { ILangString } from "@rdfjs/wrapper"
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

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

In this map example, TermMapping and ILangString are imported but never used. Removing unused imports will keep the snippet cleaner and reduce copy/paste friction for users (especially in projects with noUnusedLocals).

Suggested change
import { TermWrapper, ValueMapping, TermMapping } from "@rdfjs/wrapper"
import type { ILangString } from "@rdfjs/wrapper"
import { TermWrapper, ValueMapping } from "@rdfjs/wrapper"

Copilot uses AI. Check for mistakes.
Comment on lines +3 to +7
on:
push:
branches:
- main
workflow_dispatch:
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

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

This workflow only runs on push to main, so broken docs can be merged without CI catching it first. Consider adding a pull_request trigger (build-only; no deploy) so mkdocs build --strict runs in PRs before merge.

Copilot uses AI. Check for mistakes.
README.md Outdated
Comment on lines 114 to 115
import { ObjectMapping } from "@rdfjs/wrapper"

Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

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

This Nested Objects snippet imports only ObjectMapping but uses TermWrapper (and Address) in the example. If the intent is a copy/pasteable snippet, please add the missing imports/definitions; otherwise consider calling out that the example is abbreviated.

Suggested change
import { ObjectMapping } from "@rdfjs/wrapper"
import { TermWrapper, ObjectMapping } from "@rdfjs/wrapper"
class Address extends TermWrapper {
// Define address-related mappings here, e.g. street, city, etc.
}

Copilot uses AI. Check for mistakes.
Comment on lines +47 to +50
```typescript
@getter("https://schema.org/name", GetterArity.SingularNullable, ValueMapping.literalToString)
get name(): string | undefined {
throw new Error() // replaced by decorator
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

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

The examples below use ValueMapping and TermMapping, but the Import section at the top only shows importing getter, setter, GetterArity, and SetterArity. Consider updating the import snippet (or adding an additional one) so the examples are self-contained/copy-pasteable.

Copilot uses AI. Check for mistakes.
README.md Outdated
Comment on lines +132 to +137
```javascript
import { getter, setter, GetterArity, SetterArity, ValueMapping, TermMapping } from "@rdfjs/wrapper"

Class usage:
class Person extends TermWrapper {
@getter("https://schema.org/name", GetterArity.SingularNullable, ValueMapping.literalToString)
get name() { throw new Error() }
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

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

This decorators example is marked as javascript, but it uses TypeScript/TC39 decorators (@getter, @setter). Also, the snippet extends TermWrapper without importing it in this block, so copy/paste won’t run as-is. Consider changing the fence to typescript and including TermWrapper (or explicitly labeling the snippet as partial/pseudocode) plus a short note about the required TS decorator configuration.

Copilot uses AI. Check for mistakes.
arity: GetterArity,
valueMapping: IValueMapping<any>,
termMapping?: ITermMapping<any>,
): ClassGetterDecoratorContext => ClassGetterDecoratorContext
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

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

The documented getter(...) signature/return type here doesn’t match the actual implementation (a decorator factory that returns a function (target, context) => replacementGetter). As written, ClassGetterDecoratorContext => ClassGetterDecoratorContext is not a correct type shape and may confuse readers. Please update the signature to reflect that getter(...) returns a class getter decorator function.

Suggested change
): ClassGetterDecoratorContext => ClassGetterDecoratorContext
): (target: unknown, context: ClassGetterDecoratorContext) => () => unknown

Copilot uses AI. Check for mistakes.
predicate: string,
arity: SetterArity,
termMapping: ITermMapping<any>,
): ClassSetterDecoratorContext => ClassSetterDecoratorContext
Copy link

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

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

Similarly, the documented setter(...) signature/return type doesn’t match the implementation (a decorator factory returning (target, context) => replacementSetter). Updating the type shape here will make the API reference accurate for TypeScript users.

Suggested change
): ClassSetterDecoratorContext => ClassSetterDecoratorContext
): (target: any, context: ClassSetterDecoratorContext) => (value: any) => void

Copilot uses AI. Check for mistakes.
@jeswr
Copy link
Collaborator

jeswr commented Mar 21, 2026

@copilot apply changes based on the comments in this thread

Co-authored-by: jeswr <63333554+jeswr@users.noreply.github.com>
Agent-Logs-Url: https://github.com/rdfjs/wrapper/sessions/e3ef5d26-0106-4349-ad27-8c32daab5868
Copy link
Contributor Author

Copilot AI commented Mar 21, 2026

@copilot apply changes based on the comments in this thread

Applied all review feedback in commit 1ad3d09:

  • ObjectMapping.as return type updated to IValueMapping<T> & ITermMapping<T>
  • docs/guides/sets-and-maps.md Map example: removed unused TermMapping and ILangString imports
  • .github/workflows/docs.yml: added pull_request trigger so mkdocs build --strict runs on PRs (deploy step skipped on PRs)
  • README.md Nested Objects snippet: added TermWrapper import and Address stub class
  • README.md Decorators snippet: changed fence to typescript, added TermWrapper import and proper TypeScript types
  • docs/api/decorators.md Import section: added ValueMapping and TermMapping so examples are self-contained
  • docs/api/decorators.md getter() return type: corrected to (target: unknown, context: ClassGetterDecoratorContext) => () => unknown
  • docs/api/decorators.md setter() return type: corrected to (target: any, context: ClassSetterDecoratorContext) => (value: any) => void

Copy link
Collaborator

Choose a reason for hiding this comment

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

This one is interesting @langsamu -- I thought it was an hallucination at first because I've not encountered decorators used this way in typescript, but it turns out this syntax is indeed valid as of TypeScript 5

@jeswr
Copy link
Collaborator

jeswr commented Mar 22, 2026

@copilot In order to make sure that the examples are correct, and that the documentation remains up-to-date with breaking changes in the library; during CI, please extract all of the examples from the documentation, execute and test them in order to ensure:

    1. That the examples are correct
    1. That the examples remain up-to-date when breaking changes are made to the library

Similarly to the existing tests, please also produce a report of the coverage provided by the documentation files; to ensure that we sufficiently cover the documented API's in the documentation.

Copy link
Contributor Author

Copilot AI commented Mar 22, 2026

@copilot In order to make sure that the examples are correct, and that the documentation remains up-to-date with breaking changes in the library; during CI, please extract all of the...

Done in commit 36552d2. Here's what was added:

test/docs/ — 6 new test files (43 tests total) that execute every complete runnable example from the documentation:

  • term-wrapper.test.ts — Complete Example from guides/term-wrapper.md
  • nested-objects.test.ts — Person/Address, Recursive References, Sets of Objects from guides/nested-objects.md
  • sets-and-maps.test.ts — Set of Primitives, Set of Wrapped Objects, Map of Language Strings from guides/sets-and-maps.md
  • rdf-lists.test.ts — Full Playlist example including push/shift/pop/unshift from guides/rdf-lists.md
  • dataset-wrapper.test.ts — People dataset wrapper from guides/dataset-wrapper.md
  • decorators.test.ts — Article/Tag example, equivalence to manual mappings, and Full Decorated Class from guides/decorators.md + api/decorators.md

The docs tests are automatically included in npm test (the **/*.test.js glob picks up test/dist/docs/), so CI catches broken examples on every push.

npm run test:docs — new script that runs only the documentation tests with --experimental-test-coverage to produce a docs-specific coverage report. Docs examples alone cover 76.30% of lines, 91.02% of branches, 61.73% of functions. Combined with the unit tests, overall coverage improved from 87.10% → 89.58% (lines) and 78.40% → 82.10% (functions).

Also fixed a doc bug found during testing: the "Full Decorated Class Example" in docs/api/decorators.md used ObjectMapping.as(Person) inside the Person class's own decorator — a TypeScript temporal dead zone error. The example is updated with a manual getter for the self-referential property and an explanatory note.

Copilot AI changed the title Add MkDocs documentation site with Solid brand styling and GitHub Pages deployment Add MkDocs documentation site with Solid brand styling, GitHub Pages deployment, and doc example tests Mar 22, 2026
Copilot AI requested a review from jeswr March 22, 2026 17:59
@jeswr
Copy link
Collaborator

jeswr commented Mar 22, 2026

@copilot there should not be duplication of code between the new test files and the docs in order to avoid them getting out of sync. Please write a script which extracts the examples from the test files and adds them to the docs.

Copy link
Contributor Author

Copilot AI commented Mar 22, 2026

@copilot there should not be duplication of code between the new test files and the docs in order to avoid them getting out of sync. Please write a script which extracts the examples...

Done in commit 43882f7. Here's the architecture:

test/docs/examples/ — 10 new TypeScript files (single source of truth)

Each file contains only the class definition(s) with their @rdfjs/wrapper imports — no test infrastructure, no usage code. These are what tests import and what docs display:

  • term-wrapper.tsBook
  • nested-objects.tsAddress, Person
  • sets-and-maps-article.tsArticle, sets-and-maps-person.tsPerson, sets-and-maps-map.tsResource
  • rdf-lists.tsPlaylist
  • dataset-wrapper.tsPerson, People
  • decorators-article.tsTag, Article, decorators-equivalence.tsArticleManual/ArticleDecorated, decorators-person.tsFriend/PersonDecorated

test/docs/*.test.ts — rewritten to import classes from example files. No class body duplication remains.

scripts/sync-doc-examples.mjs — the sync script. Reads each file in test/docs/examples/, finds the matching <!-- example: STEM --> ... <!-- /example --> slot in docs, and replaces the code block content. Run modes:

  • npm run sync-doc-examples — updates docs in place
  • npm run check-doc-examples — exits 1 if any doc is out of sync (suitable for CI)

Docs — each Complete Example code block is now split into a synced class-definition block (marked with <!-- example: STEM -->) and an inline usage block showing DataFactory/Store setup with console.log demonstrations.

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
@jeswr
Copy link
Collaborator

jeswr commented Mar 22, 2026

@copilot please add CI to check that the doc examples are in sync

Copy link
Contributor Author

Copilot AI commented Mar 22, 2026

@copilot please add CI to check that the doc examples are in sync

Done in commit 9d384d1. Added npm run check-doc-examples as a step in the test job in .github/workflows/ci.yml — it runs on every push across all three OS matrix targets (macOS, Ubuntu, Windows) after npm test, and exits 1 if any doc code block is out of sync with its example file.

Running the check also revealed two stale imports in the docs (an unused TermMapping in the decorators equivalence block, and an unused ValueMapping in the sets-and-maps map block) which have been fixed by the sync script in the same commit.

@jeswr
Copy link
Collaborator

jeswr commented Mar 22, 2026

@langsamu I am happy with this PR, could you please take a quick glance and then merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants