chore: upgrade docs tooling (#238)

* chore: remove comments from tsconfig.json to prevent formatting churn

* chore: upgrade documentation tooling

* chore: exclude tests from builds

* chore: add developer script for cleaning up build output

* docs: improve the clarity of the documentation

* docs: support source urls on vercel

* chore: rename webSocket property and mark as internal

* chore: rename BaseNotificationOptions to NotificationOptions

* chore: upgrade browser testApp

This updates the dependencies, build target, and uses `file:` referenced version of this SDK when testing, no more `npm link`

.eslintrc.js

@@ -23,7 +23,8 @@ module.exports = {
   rules: {
     "import/prefer-default-export": 0,
     "max-classes-per-file": 0,
-    "jest/no-disabled-tests": 1
+    "jest/no-disabled-tests": 1,
+    "no-shadow": [1, { allow: ["NotificationOptions"] }],
   },
   parserOptions: {
     project: "./tsconfig.eslint.json",

.github/workflows/e2e-browser.yml

@@ -30,7 +30,7 @@ jobs:
     - run: npm ci
     - run: npm run build
     - run: npx playwright install --with-deps
-    - run: npm run test:e2e:browser:build
+    - run: npm run test:e2e:browser:setup
     - run: npm run test:e2e:browser
       env:
         E2E_TEST_ENVIRONMENT: ${{ matrix.environment-name }}
@@ -51,4 +51,4 @@ jobs:
       continue-on-error: true
       with:
         name: dist
-        path: dist
+        path: dist

.gitignore

@@ -8,6 +8,7 @@ LICENSE_DEPENDENCIES
 LICENSE_DEPENDENCIES_ALL
 docs/api/build/
 docs/api/source/api/
+docs/api/docs-assets/
 docs/dist/
 docs/.DS_Store
 .env*.local

docs/api/README.md → docs/README.md

@@ -15,28 +15,31 @@ To build:
    source <path to the new virtual environment>/bin/activate
    ```
 
-2. Generate the API .md files:
+2. Install the dependencies:
 
-   npm ci; npm run build-api-docs
+   ```sh
+   npm ci
+   npm run docs:install
+   ```
 
-3. Go to the directory for API docs:
+3. Generate the docs source files and build the site:
 
-   cd docs/api
+   ```sh
+   npm run docs:build
+   ```
 
-4. Install the docs requirements (different from library docs requirements):
+4. If you want to preview the docs site, you can use:
 
    ```sh
-   pip install -r requirements.txt
+   npm run docs:preview
    ```
 
-5. Make the API docs:
+5. If you'd like to clean the generated docs and start fresh, you can use:
 
    ```sh
-   make html
+   npm run docs:clean
    ```
 
-   There should be a `build/html` directory with the html artifacts.
-
 When finished, can deactivate your virtual env.
 
 ## Third Party Licenses

docs/api/Makefile

@@ -8,7 +8,7 @@ SOURCEDIR     = source
 GIT_BRANCH    :=$(shell git rev-parse --abbrev-ref HEAD)
 BUILDDIR      = build
 SPHINXOPTS    = -d $(BUILDDIR)/doctrees -W 
-SOURCECOPYDIR = $(BUILDDIR)/source/
+SOURCECOPYDIR = $(BUILDDIR)/source
 
 # Will need later for scrubbing generated .md files
 MY_OS         :=$(shell uname)
@@ -17,47 +17,45 @@ ifeq ($(MY_OS),Darwin)
 	IS_MAC="DEFINED"
 endif
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCECOPYDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+.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/README.md))
 
-.PHONY: help clean Makefile migrate html
+# 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 build/docs-assets ]; then rm -rf build/docs-assets ; fi;
-
-migrate: clean
+	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)
-
-	git clone https://github.com/inrupt/docs-assets.git build/docs-assets
-
-   # Copying to SOURCECOPYDIR instead of copying source dir to BUILDDIR
-   # in case someone forgets to backslash after build/
-   # Copying source/api/modules -> build/source/modules
-   # Copying source/api/classes -> build/source/classes
-   # Otherwise, after building the docs, the url is dev-tools/api/js/solid-client/api/modules or such.
-
 	cp -R $(SOURCEDIR)/index.rst $(SOURCECOPYDIR)
-	cp -R $(SOURCEDIR)/api/modules/ $(SOURCECOPYDIR)/modules/
-	cp -R $(SOURCEDIR)/api/classes/ $(SOURCECOPYDIR)/classes/
-
-html: Makefile migrate
-
-# To clean up cross-reference links in markdown (foo.md#somesection) 
-# If making html (e.g. foo.html), use sed to change .md# to .html#
-# Also, on macOS, need -i '' but not for Linux
-
-ifdef IS_MAC
-	find . $(SOURCECOPYDIR) -type f -name "*.md" -exec sed -i '' -e 's?\.md#?\.html#?g' {} \;
-else
-	find . $(SOURCECOPYDIR) -type f -name "*.md" -exec sed -i  -e 's?\.md#?\.html#?g' {} \;
-endif
+	cp -R $(SOURCEDIR)/api/* $(SOURCECOPYDIR)
+# Note: remove the typedoc generated `index.md` since we use a custom index.rst instead
+	rm $(SOURCECOPYDIR)/index.md
+
+html: Makefile check prepare
 	@$(SPHINXBUILD) -M $@ "$(SOURCECOPYDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c .
 
+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 migrate
+%: Makefile check prepare
 	@$(SPHINXBUILD) -M $@ "$(SOURCECOPYDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c .
-

docs/api/conf.py

@@ -52,13 +52,15 @@
 
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['./build/docs-assets/_templates']
+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 = [ ]
 
+extlinks = { }
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -67,17 +69,17 @@
 #html_theme = 'alabaster'
 
 html_theme = 'inrupt'
-html_theme_path = ['./build/docs-assets/themes']
+html_theme_path = ['./docs-assets/themes']
 
 html_copy_source = False
 
-html_title = 'Inrupt {0} API Documentation'.format(name)
+html_title = 'Inrupt {0} Documentation'.format(name)
 
 # 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),
+    'project_title': '@inrupt/{0} API'.format(name),
     'banner': True,
     'banner_msg': 'This is an Alpha release of the API.',
     'robots_index': True,
@@ -87,26 +89,26 @@
     'github_branch': 'main',
     'docs_project': 'developer-tools/api/javascript/{0}'.format(name),
     'show_api_menu': True,
-
+    
     # below are pydata_sphinx_theme
     "footer_items": [ "copyright.html"],
     "navbar_align": "left",
     "icon_links": [
         {
-            "name": "Inrupt on Twitter",
-            "url": "https://twitter.com/inrupt",
-            "icon": "fab fa-twitter-square",
-        },
-        {
-            "name": "Inrupt on LinkedIn",
-            "url": "https://www.linkedin.com/company/inrupt/",
-            "icon": "fab fa-linkedin",
+            "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",
+        },
     ],
     "favicons": [
         {
@@ -120,11 +122,46 @@
 # 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 = ['./build/docs-assets/_static']
+html_static_path = ['./docs-assets/_static']
 
 html_sidebars = {
-    '**': [  'search-field.html',  'docs-sidebar.html'],
+    '**': [ 'search-field.html',  'docs-sidebar.html'],
 }
 
 locale_dirs = ['locale/']   # path is example but recommended.
 gettext_compact = False     # optional.
+
+myst_heading_anchors = 6
+myst_url_schemes = [ 'https' ]
+myst_enable_extensions = ['colon_fence']
+
+
+# Typedoc by default outputs all files as relative to their directory, but for
+# Interfaces this is not what we want. Instead of
+# `modules/type_IssueAccessRequestParameters.html` we want
+# `interfaces/interfaces.IssueAccessRequestParameters.html`, additionally, we
+# don't want a Module generated for all the Interfaces.
+#
+# This code removes the link from generated Interfaces to the Interfaces Module,
+# and also excludes the Interfaces Module from being generated.
+#
+# This does require a doccomment of:
+# 
+#   /**
+#    * @module interfaces
+#    */
+# 
+# On each typescript file that declares Interfaces in src/types/*
+#
+# duplicateInterfaceHeading = re.compile(r"^\[interfaces\]\([^\)]+\)\.(\w+)$", re.MULTILINE)
+
+# def remove_interfaces_link(app, docname, source):  
+#     if docname.startswith("interfaces/"):
+#         # First we strip the duplicate heading that typedoc inserts:
+#         source[0] = re.sub(duplicateInterfaceHeading, "", source[0])
+#         # Then we remove any other links to the Interfaces module:
+#         source[0] = source[0].replace("[interfaces](../modules/interfaces.md)", "Interfaces")
+
+# def setup(app):
+#     exclude_patterns.append("modules/interfaces.md")
+#     app.connect("source-read", remove_interfaces_link) 

docs/api/requirements.txt

@@ -1,5 +1,5 @@
 # pip install -r requirements.txt
 
-pydata-sphinx-theme==0.6.3
-myst-parser
-Sphinx
+pydata-sphinx-theme==0.8.1
+myst-parser==0.17.0
+Sphinx==4.5.0