Skip to content

Commit c0082ee

Browse files
edwardsphclaude
edwardsph
and
claude
committed
Simplify API documentation with TypeDoc
- Replace complex Sphinx/Python setup with standard TypeDoc - Move TypeDoc config from tsconfig.json to standalone typedoc.config.json - Update doc build scripts to use TypeDoc directly - Add GitHub Action workflow for GitHub Pages deployment - Update documentation for new approach - Add instructions for Sphinx removal 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent a78b2bf commit c0082ee

6 files changed

Lines changed: 226 additions & 92 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Build and Deploy API Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'src/**'
9+
- 'typedoc.config.json'
10+
- '.github/workflows/docs.yml'
11+
workflow_dispatch:
12+
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
concurrency:
19+
group: "pages"
20+
cancel-in-progress: false
21+
22+
jobs:
23+
build:
24+
runs-on: ubuntu-latest
25+
steps:
26+
- name: Checkout
27+
uses: actions/checkout@v4
28+
29+
- name: Setup Node
30+
uses: actions/setup-node@v4
31+
with:
32+
node-version: '22'
33+
cache: 'npm'
34+
35+
- name: Install dependencies
36+
run: npm ci
37+
38+
- name: Build documentation
39+
run: npm run docs:build
40+
41+
- name: Setup Pages
42+
uses: actions/configure-pages@v4
43+
44+
- name: Upload artifact
45+
uses: actions/upload-pages-artifact@v3
46+
with:
47+
path: './docs/dist'
48+
49+
deploy:
50+
environment:
51+
name: github-pages
52+
url: ${{ steps.deployment.outputs.page_url }}
53+
runs-on: ubuntu-latest
54+
needs: build
55+
steps:
56+
- name: Deploy to GitHub Pages
57+
id: deployment
58+
uses: actions/deploy-pages@v4

‎REMOVE_SPHINX.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Sphinx Removal Guide
2+
3+
This document explains how to complete the removal of Sphinx-related files and dependencies after the migration to TypeDoc for API documentation.
4+
5+
## Files and Directories to Remove
6+
7+
Once the new TypeDoc-based documentation is working correctly, the following files and directories can be safely removed:
8+
9+
- `/docs/api/Makefile`: Sphinx build script
10+
- `/docs/api/conf.py`: Sphinx configuration file
11+
- `/docs/api/redirects.txt`: Redirects for Sphinx
12+
- `/docs/api/source/`: Sphinx source files
13+
- `/docs/api/themes/`: Sphinx themes
14+
15+
## Dependencies to Remove
16+
17+
You no longer need the Python dependencies that were previously used for Sphinx. The Python virtual environment can be removed as well.
18+
19+
## Steps for Cleanup
20+
21+
1. First, verify that the new TypeDoc system is working correctly:
22+
```bash
23+
npm run docs:clean
24+
npm run docs:build
25+
npm run docs:preview
26+
```
27+
28+
2. Delete the Sphinx-related files:
29+
```bash
30+
rm -rf docs/api/
31+
```
32+
33+
3. Remove any remaining Python virtual environment in the project root:
34+
```bash
35+
rm -rf venv/
36+
```
37+
38+
4. Update the `.gitignore` file to remove any Sphinx-related patterns if present
39+
40+
## Notes
41+
42+
- The cleanup can be done in a separate PR after confirming that the new documentation system works correctly
43+
- Keep any custom content from the Sphinx documentation that should be preserved in the new system

‎docs/README.md‎

Lines changed: 46 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,63 @@
1-
# apidocs
1+
# @inrupt/solid-client API Documentation
22

3-
Builds the API docs site from generated api \*.md files.
3+
This directory contains the TypeScript API documentation setup for the `@inrupt/solid-client` library.
44

5-
## To Build
5+
## Documentation Structure
66

7-
To build:
7+
- `docs/dist/`: Generated HTML documentation (output of TypeDoc)
8+
- `typedoc.config.json`: Configuration for TypeDoc in the root directory
89

9-
0. Prereq: [python3](https://www.python.org/downloads/), [Node.js](https://nodejs.org/).
10+
## Building Documentation
1011

11-
1. Optional but recommended. Create a virtual env:
12+
To build the documentation locally:
1213

13-
```sh
14-
python3 -m venv <path to the new virtual environment>
15-
source <path to the new virtual environment>/bin/activate
16-
```
14+
```bash
15+
# Install dependencies
16+
npm ci
1717

18-
2. Install the dependencies:
18+
# Build documentation
19+
npm run docs:build
1920

20-
```sh
21-
npm ci
22-
npm run docs:install
23-
```
21+
# Preview documentation on http://localhost:8080
22+
npm run docs:preview
23+
```
2424

25-
3. Generate the docs source files and build the site:
25+
## Documentation Configuration
2626

27-
```sh
28-
npm run docs:build
29-
```
27+
The TypeDoc configuration is isolated in `typedoc.config.json` in the project root to allow for easy reuse across repositories. The key aspects of the configuration include:
3028

31-
4. If you want to preview the docs site, you can use:
29+
- **Entry Points**: Explicitly lists all the source files that should be documented
30+
- **Exclusions**: Specifies files to exclude from documentation (tests, internal files)
31+
- **Theme**: Uses the default TypeDoc theme for HTML output
32+
- **Output**: Generates documentation to `docs/dist/`
3233

33-
```sh
34-
npm run docs:preview
35-
```
34+
## Deployment
3635

37-
5. If you'd like to clean the generated docs and start fresh, you can use:
36+
The documentation is automatically built and deployed to GitHub Pages when changes are pushed to the main branch or when documentation-related files are modified.
3837

39-
```sh
40-
npm run docs:clean
41-
```
38+
The GitHub Action workflow (`.github/workflows/docs.yml`) handles:
39+
1. Building the documentation using the TypeDoc configuration
40+
2. Deploying the generated HTML to GitHub Pages
4241

43-
When finished, can deactivate your virtual env.
42+
## Customizing for Other Repositories
4443

45-
## Third Party Licenses
44+
To use this documentation setup in other `@inrupt` repositories:
4645

47-
The `requirements.txt` lists the 3rd party libraries used for the docs.
48-
For the licenses, see the shared
49-
[inrupt/docs-assets](https://github.com/inrupt/docs-assets#readme).
46+
1. Copy `typedoc.config.json` to the target repository
47+
2. Update the entry points to match the repository's structure
48+
3. Copy the scripts from `package.json`:
49+
- `docs:clean`: Cleans previous documentation
50+
- `docs:build`: Builds documentation with TypeDoc
51+
- `docs:preview`: Starts a local server to preview documentation
52+
4. Copy the GitHub Action workflow from `.github/workflows/docs.yml`
53+
54+
## Future Improvements
55+
56+
For shared configuration across repositories, consider:
57+
58+
1. Creating an `@inrupt/internal-typedoc-config` package with:
59+
- Base TypeDoc configuration
60+
- Common themes and plugins
61+
- Shared GitHub Actions workflow templates
62+
63+
2. Each repository would then extend the base configuration with its specific entry points and customize as needed.

‎package.json‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,9 @@
55
"license": "MIT",
66
"scripts": {
77
"build": "rollup --config rollup.config.mjs",
8-
"docs:clean": "cd docs/api; make clean-all",
9-
"docs:install": "cd docs/api; pip install -r https://raw.githubusercontent.com/inrupt/docs-assets/main/requirements/api/requirements.txt",
10-
"docs:build": "typedoc && cd docs/api && make html dist",
11-
"docs:preview": "python3 -m http.server --bind 127.0.0.1 --directory docs/dist",
8+
"docs:clean": "rimraf docs/dist",
9+
"docs:build": "typedoc --options typedoc.config.json",
10+
"docs:preview": "http-server --port 8080 docs/dist",
1211
"check-licenses": "license-checker --production --failOn \"AGPL-1.0-only; AGPL-1.0-or-later; AGPL-3.0-only; AGPL-3.0-or-later; Beerware; CC-BY-NC-1.0; CC-BY-NC-2.0; CC-BY-NC-2.5; CC-BY-NC-3.0; CC-BY-NC-4.0; CC-BY-NC-ND-1.0; CC-BY-NC-ND-2.0; CC-BY-NC-ND-2.5; CC-BY-NC-ND-3.0; CC-BY-NC-ND-4.0; CC-BY-NC-SA-1.0; CC-BY-NC-SA-2.0; CC-BY-NC-SA-2.5; CC-BY-NC-SA-3.0; CC-BY-NC-SA-4.0; CPAL-1.0; EUPL-1.0; EUPL-1.1; EUPL-1.1; GPL-1.0-only; GPL-1.0-or-later; GPL-2.0-only; GPL-2.0-or-later; GPL-3.0; GPL-3.0-only; GPL-3.0-or-later; SISSL; SISSL-1.2; WTFPL\"",
1312
"lint": "npm run lint:check",
1413
"lint:fix": "npm run lint:eslint -- --fix && npm run lint:prettier -- --write",
@@ -187,15 +186,16 @@
187186
"eslint": "^8.56.0",
188187
"eslint-config-next": "^15.0.1",
189188
"fast-check": "^3.15.0",
189+
"http-server": "^14.1.1",
190190
"jest": "^29.7.0",
191191
"jest-environment-jsdom": "^29.7.0",
192192
"prettier": "3.5.3",
193193
"rdf-isomorphic": "^1.3.1",
194194
"rdf-namespaces": "^1.12.0",
195+
"rimraf": "^5.0.5",
195196
"rollup": "^4.9.1",
196197
"ts-jest": "^29.1.1",
197198
"typedoc": "^0.28.0",
198-
"typedoc-plugin-markdown": "^3.17.1",
199199
"typescript": "^5.3.3",
200200
"webpack": "^5.89.0",
201201
"webpack-cli": "^6.0.1"

‎tsconfig.json‎

Lines changed: 1 addition & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -15,61 +15,7 @@
1515
// Advanced Options
1616
"stripInternal": true
1717
},
18-
"typedocOptions": {
19-
"out": "docs/api/source/api",
20-
"hideInPageTOC": true,
21-
"entryPoints": [
22-
// The source files of everything listed under `exports` in our package.json
23-
// (i.e. public API's that should be documented) should be listed here:
24-
"src/interfaces.ts",
25-
"src/resource/resource.ts",
26-
"src/resource/solidDataset.ts",
27-
"src/resource/file.ts",
28-
"src/resource/mock.ts",
29-
"src/thing/thing.ts",
30-
"src/thing/get.ts",
31-
"src/thing/set.ts",
32-
"src/thing/add.ts",
33-
"src/thing/remove.ts",
34-
"src/thing/build.ts",
35-
"src/thing/mock.ts",
36-
"src/acl/acl.ts",
37-
"src/acl/agent.ts",
38-
"src/acl/group.ts",
39-
"src/acl/class.ts",
40-
"src/acl/mock.ts",
41-
"src/universal/index.ts",
42-
"src/acp/ess2.ts",
43-
"src/acp/ess1.ts",
44-
"src/rdfjs.ts",
45-
"src/profile/jwks.ts",
46-
"src/profile/webid.ts",
47-
"src/formats/index.ts"
48-
],
49-
"exclude": [
50-
"node_modules/**",
51-
"**/*.test.ts",
52-
// Internal helpers:
53-
"**/*.internal.ts",
54-
// End-to-end tests:
55-
"e2e/**",
56-
// Re-exported functions are already documented in their own modules:
57-
"src/index.ts",
58-
// Constants are only used internally:
59-
"src/constants.ts",
60-
// Helper methods for working with raw RDF internally:
61-
"src/datatypes.ts",
62-
// Behind-the-scenes auto-detection of the right fetcher to use:
63-
"src/fetcher.ts",
64-
// Helper methods for working with raw Turtle internally:
65-
"src/formats/turtle.ts",
66-
"src/formats/jsonLd.ts"
67-
],
68-
"theme": "markdown",
69-
"readme": "none",
70-
"entryDocument": "index.rst",
71-
"plugin": ["typedoc-plugin-markdown"]
72-
},
18+
/* TypeDoc configuration has been moved to typedoc.config.json */
7319
"include": ["src/**/*.ts"],
7420
"exclude": [
7521
"**/node_modules",

‎typedoc.config.json‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
{
2+
"out": "docs/dist",
3+
"entryPoints": [
4+
"src/interfaces.ts",
5+
"src/resource/resource.ts",
6+
"src/resource/solidDataset.ts",
7+
"src/resource/file.ts",
8+
"src/resource/mock.ts",
9+
"src/thing/thing.ts",
10+
"src/thing/get.ts",
11+
"src/thing/set.ts",
12+
"src/thing/add.ts",
13+
"src/thing/remove.ts",
14+
"src/thing/build.ts",
15+
"src/thing/mock.ts",
16+
"src/acl/acl.ts",
17+
"src/acl/agent.ts",
18+
"src/acl/group.ts",
19+
"src/acl/class.ts",
20+
"src/acl/mock.ts",
21+
"src/universal/index.ts",
22+
"src/acp/ess2.ts",
23+
"src/acp/ess1.ts",
24+
"src/rdfjs.ts",
25+
"src/profile/jwks.ts",
26+
"src/profile/webid.ts",
27+
"src/formats/index.ts"
28+
],
29+
"exclude": [
30+
"node_modules/**",
31+
"**/*.test.ts",
32+
"**/*.internal.ts",
33+
"e2e/**",
34+
"src/index.ts",
35+
"src/constants.ts",
36+
"src/datatypes.ts",
37+
"src/fetcher.ts",
38+
"src/formats/turtle.ts",
39+
"src/formats/jsonLd.ts"
40+
],
41+
"theme": "default",
42+
"name": "@inrupt/solid-client API Documentation",
43+
"includeVersion": true,
44+
"readme": "README.md",
45+
"hideGenerator": true,
46+
"plugin": [],
47+
"validation": {
48+
"invalidLink": true,
49+
"notDocumented": true
50+
},
51+
"visibilityFilters": {
52+
"protected": false,
53+
"private": false,
54+
"inherited": true,
55+
"external": false
56+
},
57+
"navigationLinks": {
58+
"Inrupt Documentation": "https://docs.inrupt.com/",
59+
"GitHub": "https://github.com/inrupt/solid-client-js"
60+
},
61+
"categoryOrder": [
62+
"Core",
63+
"Resource",
64+
"Thing",
65+
"Access Control",
66+
"Formats",
67+
"Profile",
68+
"*"
69+
],
70+
"categorizeByGroup": false,
71+
"searchInComments": true,
72+
"cleanOutputDir": true
73+
}

0 commit comments

Comments
 (0)