diff --git a/.github/workflows/api-docs.yml b/.github/workflows/api-docs.yml new file mode 100644 index 0000000000..baff842bea --- /dev/null +++ b/.github/workflows/api-docs.yml @@ -0,0 +1,46 @@ +name: API docs + +on: + push: + branches: [ "main" ] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + - name: Install dependencies + run: npm ci + - name: Generate API docs site + run: npx typedoc + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./docs/api + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 7a74d3c621..19d9131275 100644 --- a/.gitignore +++ b/.gitignore @@ -6,9 +6,7 @@ umd whitesource/ LICENSE_DEPENDENCIES LICENSE_DEPENDENCIES_ALL -docs/api/build/ -docs/api/source/api/ -docs/api/docs-assets/ +docs/api/ docs/dist/ .env*.local .codesandbox/sandbox/.parcel-cache/ diff --git a/docs/api/Makefile b/docs/api/Makefile deleted file mode 100644 index 25360ac9de..0000000000 --- a/docs/api/Makefile +++ /dev/null @@ -1,64 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -GIT_BRANCH :=$(shell git rev-parse --abbrev-ref HEAD) -BUILDDIR = build -SPHINXOPTS = -d $(BUILDDIR)/doctrees -W -SOURCECOPYDIR = $(BUILDDIR)/source - -# Will need later for scrubbing generated .md files -MY_OS :=$(shell uname) -# In Makefile, spaces and everything count inside if parens() -ifeq ($(MY_OS),Darwin) - IS_MAC="DEFINED" -endif - -.PHONY: Makefile help check clean clean-all prepare html dist - -check: - $(if $(shell command -v $(SPHINXBUILD) 2> /dev/null),$(info Found `$(SPHINXBUILD)`),$(error sphinx-build is not available, please follow the instructions in ./docs/api/README.md)) - -# Put it first so that "make" without argument is like "make help". -help: check - @$(SPHINXBUILD) -M help "$(SOURCECOPYDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -clean: - if [ -d $(BUILDDIR) ]; then rm -rf $(BUILDDIR) ; fi; - if [ -d ../dist ]; then rm -rf ../dist ; fi; - -# clean-all has to be separate from clean as prepare depends on clean, -# but prepare also expects the typedoc build output to exist in source/api -clean-all: clean - if [ -d docs-assets ]; then rm -rf docs-assets ; fi; - if [ -d source/api ]; then rm -rf source/api ; fi; - -prepare: clean - if [ ! -d docs-assets ]; then git clone https://github.com/inrupt/docs-assets.git docs-assets; fi; -# Copying to SOURCECOPYDIR instead of copying source dir to BUILDDIR -# in case someone forgets to backslash after build/ -# Copying source/api/* to BUILDDIR. - - mkdir -p $(SOURCECOPYDIR) - cp -R $(SOURCEDIR)/api/* $(SOURCECOPYDIR) -# Note: remove the typedoc generated `index.rst` (see tsconfig.json) since we use a custom index.rst instead - rm $(SOURCECOPYDIR)/index.rst - -# Use our custom index.rst - cp -R $(SOURCEDIR)/index.rst $(SOURCECOPYDIR) - -html: Makefile check prepare - @$(SPHINXBUILD) -M $@ "$(SOURCECOPYDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c . --keep-going - -dist: html - if [ -d ../dist ]; then rm -r ../dist; fi; - mkdir -p ../dist - cp -R $(BUILDDIR)/html/. ../dist/ - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile check prepare - @$(SPHINXBUILD) -M $@ "$(SOURCECOPYDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c . --keep-going diff --git a/docs/api/conf.py b/docs/api/conf.py deleted file mode 100644 index 30a81a8d11..0000000000 --- a/docs/api/conf.py +++ /dev/null @@ -1,136 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - -# -- Project information ----------------------------------------------------- - -from sphinx.highlighting import lexers -import datetime - -copyright = u'{0} Inrupt Inc.'.format(datetime.date.today().year) - -# -- General configuration --------------------------------------------------- - - -# -- product name ----- -# -- Separately update code samples and toc links and docs-navbar since not using substitutions-- - -name = 'solid-client' -repo_name = '{0}-js'.format(name) - -pygments_style = 'sphinx' - -# -- Using .txt instead of .rst for restructured text ----------------------- -source_suffix = { - '.rst': 'restructuredtext', - '.md': 'markdown', -} - -# -- Add lexers - -highlight_language = 'javascript' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - 'sphinx.ext.extlinks', - 'myst_parser', -] - - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['./docs-assets/_templates'] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -#html_theme = 'alabaster' - -html_theme = 'inrupt' -html_theme_path = ['./docs-assets/themes'] - -html_copy_source = False - -html_title = 'Inrupt {0} Documentation'.format(name) -html_favicon= "https://docs.inrupt.com/inrupt_stickers_v2-03.png" - -# These theme options are declared in ./themes/inrupt/theme.conf -# as well as some for pydata_sphinx_theme - -html_theme_options = { - 'project_title': '@inrupt/{0} API'.format(name), - 'banner': False, - 'banner_msg': '', - 'robots_index': True, - 'github_editable': False, - 'github_org': 'inrupt', - 'github_repo': repo_name, - 'github_branch': 'main', - 'docs_project': 'developer-tools/api/javascript/{0}'.format(name), - 'show_api_menu': True, - - # below are pydata_sphinx_theme - "footer_start": ["copyright.html"], - "footer_end": [ ], - "navbar_align": "left", - "icon_links": [ - { - "name": "Support Desk", - "url": "https://inrupt.atlassian.net/servicedesk", - "icon": "fas fa-tools", - }, - { - "name": "Solid forum", - "url": "https://forum.solidproject.org/", - "icon": "fas fa-users", - }, - { - "name": "Inrupt Blog", - "url": "https://inrupt.com/blog", - "icon": "fas fa-blog", - }, - ], -} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['./docs-assets/_static'] -html_css_files = [ - 'css/inrupt.css', -] - -html_sidebars = { - '**': ['search-field.html', 'docs-sidebar.html'], -} - -html_context = { - "default_mode": "auto" -} - -locale_dirs = ['locale/'] # path is example but recommended. -gettext_compact = False # optional. - -myst_heading_anchors = 6 -myst_url_schemes = ('https', 'http') -myst_enable_extensions = ['colon_fence'] diff --git a/docs/api/redirects.txt b/docs/api/redirects.txt deleted file mode 100644 index 9b5549ac26..0000000000 --- a/docs/api/redirects.txt +++ /dev/null @@ -1,28 +0,0 @@ -developer-tools/api/javascript/solid-client/README.html -> developer-tools/api/javascript/solid-client/index.html -developer-tools/api/javascript/solid-client/classes/_resource_resource_.fetcherror.html -> developer-tools/api/javascript/solid-client/classes/resource_resource.fetcherror.html -developer-tools/api/javascript/solid-client/classes/_thing_thing_.thingexpectederror.html -> developer-tools/api/javascript/solid-client/classes/thing_thing.thingexpectederror.html -developer-tools/api/javascript/solid-client/classes/_thing_thing_.validpropertyurlexpectederror.html -> developer-tools/api/javascript/solid-client/classes/thing_thing.validpropertyurlexpectederror.html -developer-tools/api/javascript/solid-client/classes/_thing_thing_.validthingurlexpectederror.html -> developer-tools/api/javascript/solid-client/classes/thing_thing.validthingurlexpectederror.html -developer-tools/api/javascript/solid-client/classes/_thing_thing_.validvalueurlexpectederror.html -> developer-tools/api/javascript/solid-client/classes/thing_thing.validvalueurlexpectederror.html -developer-tools/api/javascript/solid-client/modules/_acl_acl_.html -> developer-tools/api/javascript/solid-client/modules/acl_acl.html -developer-tools/api/javascript/solid-client/modules/_acl_agent_.html -> developer-tools/api/javascript/solid-client/modules/acl_agent.html -developer-tools/api/javascript/solid-client/modules/_acl_class_.html -> developer-tools/api/javascript/solid-client/modules/acl_class.html -developer-tools/api/javascript/solid-client/modules/_acl_group_.html -> developer-tools/api/javascript/solid-client/modules/acl_group.html -developer-tools/api/javascript/solid-client/modules/_acl_mock_.html -> developer-tools/api/javascript/solid-client/modules/acl_mock.html -developer-tools/api/javascript/solid-client/modules/_interfaces_.html -> developer-tools/api/javascript/solid-client/modules/interfaces.html -developer-tools/api/javascript/solid-client/modules/_resource_file_.html -> developer-tools/api/javascript/solid-client/modules/resource_file.html -developer-tools/api/javascript/solid-client/modules/_resource_mock_.html -> developer-tools/api/javascript/solid-client/modules/resource_mock.html -developer-tools/api/javascript/solid-client/modules/_resource_resource_.html -> developer-tools/api/javascript/solid-client/modules/resource_resource.html -developer-tools/api/javascript/solid-client/modules/_resource_soliddataset_.html -> developer-tools/api/javascript/solid-client/modules/resource_soliddataset.html -developer-tools/api/javascript/solid-client/modules/_resource_nonrdfdata_.html -> developer-tools/api/javascript/solid-client/modules/resource_file.html -developer-tools/api/javascript/solid-client/modules/_thing_add_.html -> developer-tools/api/javascript/solid-client/modules/thing_add.html -developer-tools/api/javascript/solid-client/modules/_thing_get_.html -> developer-tools/api/javascript/solid-client/modules/thing_get.html -developer-tools/api/javascript/solid-client/modules/_thing_mock_.html -> developer-tools/api/javascript/solid-client/modules/thing_mock.html -developer-tools/api/javascript/solid-client/modules/_thing_remove_.html -> developer-tools/api/javascript/solid-client/modules/thing_remove.html -developer-tools/api/javascript/solid-client/modules/_thing_set_.html -> developer-tools/api/javascript/solid-client/modules/thing_set.html -developer-tools/api/javascript/solid-client/modules/_thing_thing_.html -> developer-tools/api/javascript/solid-client/modules/thing_thing.html -developer-tools/api/javascript/solid-client/classes/resource/resource.fetcherror.html -> developer-tools/api/javascript/solid-client/classes/resource_resource.fetcherror.html -developer-tools/api/javascript/solid-client/classes/thing/thing.thingexpectederror.html -> developer-tools/api/javascript/solid-client/classes/thing_thing.thingexpectederror.html -developer-tools/api/javascript/solid-client/classes/thing/thing.validpropertyurlexpectederror.html -> developer-tools/api/javascript/solid-client/classes/thing_thing.validpropertyurlexpectederror.html -developer-tools/api/javascript/solid-client/classes/thing/thing.validthingurlexpectederror.html -> developer-tools/api/javascript/solid-client/classes/thing_thing.validthingurlexpectederror.html -developer-tools/api/javascript/solid-client/classes/thing/thing.validvalueurlexpectederror.html -> developer-tools/api/javascript/solid-client/classes/thing_thing.validvalueurlexpectederror.html diff --git a/docs/api/source/index.rst b/docs/api/source/index.rst deleted file mode 100644 index d6f8e9484e..0000000000 --- a/docs/api/source/index.rst +++ /dev/null @@ -1,102 +0,0 @@ -:orphan: - -@inrupt/solid-client API Documentation -====================================== - -`@inrupt/solid-client `__ -is a JavaScript library for accessing data and managing permissions on -data stored in Solid Pods. It provides an abstraction layer on top of -both Solid and Resource Description Framework (RDF) principles and is -compatible with the RDF/JS specification. You can use solid-client in -Node.js using either CommonJS or ESM modules, and in the browser with a -bundler like Webpack, Rollup, or Parcel. - -It is part of a `family open source JavaScript -libraries `__ -designed to support developers building Solid applications. - -Installation ------------- - -For the latest stable version of solid-client: - -.. code:: bash - - npm install @inrupt/solid-client - -Changelog -~~~~~~~~~ - -See `the release -notes `__. - -Supported environments -~~~~~~~~~~~~~~~~~~~~~~ - -Our JavaScript Client Libraries use relatively modern JavaScript, aligned with -the `ES2018 `__ Specification features, we -ship both `ESM `__ and -`CommonJS `__, with type -definitions for TypeScript alongside. - -This means that out of the box, we only support environments (browsers or -runtimes) that were released after mid-2018, if you wish to target other (older) -environments, then you will need to cross-compile our SDKs via the use of `Babel -`__, `webpack `__, `SWC -`__, or similar. - -If you need support for Internet Explorer, it is recommended to pass them -through a tool like `Babel `__, and to add polyfills for -e.g. ``Map``, ``Set``, ``Promise``, ``Headers``, ``Array.prototype.includes``, -``Object.entries`` and ``String.prototype.endsWith``. - -Node.js Support -^^^^^^^^^^^^^^^ - -See `Inrupt Solid Javascript Client Libraries -`__. - -.. _issues--help: - -Issues & Help -------------- - -Solid Community Forum -~~~~~~~~~~~~~~~~~~~~~ - -If you have questions about working with Solid or just want to share -what you're working on, visit the `Solid -forum `__. The Solid forum is a good -place to meet the rest of the community. - -Bugs and Feature Requests -~~~~~~~~~~~~~~~~~~~~~~~~~ - -- For public feedback, bug reports, and feature requests please file an - issue via - `Github `__. -- For non-public feedback or support inquiries please use the `Inrupt - Service Desk `__. - ------------- - -API -=== - -Modules -------- - -.. toctree:: - :glob: - :titlesonly: - - /modules/** - -Classes -------- - -.. toctree:: - :glob: - :titlesonly: - - /classes/** diff --git a/docs/api/themes/inrupt/theme.conf b/docs/api/themes/inrupt/theme.conf deleted file mode 100644 index 5f716252c9..0000000000 --- a/docs/api/themes/inrupt/theme.conf +++ /dev/null @@ -1,17 +0,0 @@ -[theme] -inherit = pydata_sphinx_theme -pygments_style = sphinx - -[options] -project_title = -banner = -banner_msg = -github_editable = -github_org = inrupt -github_repo = -github_branch = -robots_index = -ess_docs = -clientlibjs_docs = -reactsdk_docs = -docs_project = developer-tools/api/javascript/solid-client diff --git a/package-lock.json b/package-lock.json index 3ad77c53e0..9715bf884b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -42,7 +42,6 @@ "rollup": "^4.9.1", "ts-jest": "^29.1.1", "typedoc": "^0.28.0", - "typedoc-plugin-markdown": "^3.17.1", "typescript": "^5.3.3", "webpack": "^5.89.0", "webpack-cli": "^6.0.1" @@ -12697,18 +12696,6 @@ "typescript": "5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x || 5.9.x" } }, - "node_modules/typedoc-plugin-markdown": { - "version": "3.17.1", - "resolved": "https://registry.npmjs.org/typedoc-plugin-markdown/-/typedoc-plugin-markdown-3.17.1.tgz", - "integrity": "sha512-QzdU3fj0Kzw2XSdoL15ExLASt2WPqD7FbLeaqwT70+XjKyTshBnUlQA5nNREO1C2P8Uen0CDjsBLMsCQ+zd0lw==", - "dev": true, - "dependencies": { - "handlebars": "^4.7.7" - }, - "peerDependencies": { - "typedoc": ">=0.24.0" - } - }, "node_modules/typedoc/node_modules/brace-expansion": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", @@ -22452,15 +22439,6 @@ } } }, - "typedoc-plugin-markdown": { - "version": "3.17.1", - "resolved": "https://registry.npmjs.org/typedoc-plugin-markdown/-/typedoc-plugin-markdown-3.17.1.tgz", - "integrity": "sha512-QzdU3fj0Kzw2XSdoL15ExLASt2WPqD7FbLeaqwT70+XjKyTshBnUlQA5nNREO1C2P8Uen0CDjsBLMsCQ+zd0lw==", - "dev": true, - "requires": { - "handlebars": "^4.7.7" - } - }, "typescript": { "version": "5.8.3", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.8.3.tgz", diff --git a/package.json b/package.json index b16260e912..e5046094eb 100644 --- a/package.json +++ b/package.json @@ -192,7 +192,6 @@ "rollup": "^4.9.1", "ts-jest": "^29.1.1", "typedoc": "^0.28.0", - "typedoc-plugin-markdown": "^3.17.1", "typescript": "^5.3.3", "webpack": "^5.89.0", "webpack-cli": "^6.0.1" diff --git a/tsconfig.json b/tsconfig.json index 81d001c9a6..fea6e0b7dc 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -15,61 +15,6 @@ // Advanced Options "stripInternal": true }, - "typedocOptions": { - "out": "docs/api/source/api", - "hideInPageTOC": true, - "entryPoints": [ - // The source files of everything listed under `exports` in our package.json - // (i.e. public API's that should be documented) should be listed here: - "src/interfaces.ts", - "src/resource/resource.ts", - "src/resource/solidDataset.ts", - "src/resource/file.ts", - "src/resource/mock.ts", - "src/thing/thing.ts", - "src/thing/get.ts", - "src/thing/set.ts", - "src/thing/add.ts", - "src/thing/remove.ts", - "src/thing/build.ts", - "src/thing/mock.ts", - "src/acl/acl.ts", - "src/acl/agent.ts", - "src/acl/group.ts", - "src/acl/class.ts", - "src/acl/mock.ts", - "src/universal/index.ts", - "src/acp/ess2.ts", - "src/acp/ess1.ts", - "src/rdfjs.ts", - "src/profile/jwks.ts", - "src/profile/webid.ts", - "src/formats/index.ts" - ], - "exclude": [ - "node_modules/**", - "**/*.test.ts", - // Internal helpers: - "**/*.internal.ts", - // End-to-end tests: - "e2e/**", - // Re-exported functions are already documented in their own modules: - "src/index.ts", - // Constants are only used internally: - "src/constants.ts", - // Helper methods for working with raw RDF internally: - "src/datatypes.ts", - // Behind-the-scenes auto-detection of the right fetcher to use: - "src/fetcher.ts", - // Helper methods for working with raw Turtle internally: - "src/formats/turtle.ts", - "src/formats/jsonLd.ts" - ], - "theme": "markdown", - "readme": "none", - "entryDocument": "index.rst", - "plugin": ["typedoc-plugin-markdown"] - }, "include": ["src/**/*.ts"], "exclude": [ "**/node_modules", diff --git a/typedoc.config.mjs b/typedoc.config.mjs new file mode 100644 index 0000000000..3452562bda --- /dev/null +++ b/typedoc.config.mjs @@ -0,0 +1,72 @@ +// Copyright Inrupt Inc. +// +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to deal in +// the Software without restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the +// Software, and to permit persons to whom the Software is furnished to do so, +// subject to the following conditions: +// +// The above copyright notice and this permission notice shall be included in +// all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, +// INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +// SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +// + +export default { + compilerOptions: { + skipLibCheck: true, + }, + out: "docs/api/", + entryPoints: [ + // The source files of everything listed under `exports` in our package.json + // (i.e. public API's that should be documented) should be listed here: + "src/interfaces.ts", + "src/resource/resource.ts", + "src/resource/solidDataset.ts", + "src/resource/file.ts", + "src/resource/mock.ts", + "src/thing/thing.ts", + "src/thing/get.ts", + "src/thing/set.ts", + "src/thing/add.ts", + "src/thing/remove.ts", + "src/thing/build.ts", + "src/thing/mock.ts", + "src/acl/acl.ts", + "src/acl/agent.ts", + "src/acl/group.ts", + "src/acl/class.ts", + "src/acl/mock.ts", + "src/universal/index.ts", + "src/acp/ess2.ts", + "src/rdfjs.ts", + "src/profile/jwks.ts", + "src/profile/webid.ts", + "src/formats/index.ts", + ], + exclude: [ + "node_modules/**", + "**/*.test.ts", + // Internal helpers: + "**/*.internal.ts", + // End-to-end tests: + "e2e/**", + // Re-exported functions are already documented in their own modules: + "src/index.ts", + // Constants are only used internally: + "src/constants.ts", + // Helper methods for working with raw RDF internally: + "src/datatypes.ts", + // Behind-the-scenes auto-detection of the right fetcher to use: + "src/fetcher.ts", + // Helper methods for working with raw Turtle internally: + "src/formats/turtle.ts", + "src/formats/jsonLd.ts", + ], +};