chore: upgrade docs infrastructure & fix documentation builds

.eslintrc.js

@@ -22,4 +22,9 @@ module.exports = {
     "import/prefer-default-export": 0,
     "max-classes-per-file": 0,
   },
+  settings: {
+    "import/resolver": {
+      typescript: {},
+    },
+  },
 };

.gitignore

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

docs/api/Makefile

@@ -17,48 +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/api/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;
-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)
-
-   # 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/
-	cp -R $(SOURCEDIR)/api/interfaces/ $(SOURCECOPYDIR)/interfaces/
-
-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
+	cp -R $(SOURCEDIR)/api/* $(SOURCECOPYDIR)
+# Note: remove the typedoc generated `index.md` since we use a custom index.rst instead
+	rm $(SOURCECOPYDIR)/index.md
 
-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
+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
-	@$(SPHINXBUILD) -M $@ "$(SOURCECOPYDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c .
-
-
-
-
-
+%: Makefile check prepare
+	@$(SPHINXBUILD) -M $@ "$(SOURCECOPYDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -c .

docs/api/README.md

@@ -15,113 +15,35 @@ 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
 
-This section is incomplete since work in progress - and so the dependencies may change, etc. (right now, acting as placeholder - so that we don't forget)
-
-### Sphinx
-
-Copyright (c) 2007-2020 by the Sphinx team (see AUTHORS file).
-All rights reserved.
-
-### pydata-sphinx-theme
-
-The documentation's theme is based on the [pydata-sphinx-theme](https://github.com/pandas-dev/pydata-sphinx-theme), which is under the BSD-3-Clause license:
-
-BSD 3-Clause License
-
-Copyright (c) 2018, pandas
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-- Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
-
-- Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
-
-- Neither the name of the copyright holder nor the names of its
-  contributors may be used to endorse or promote products derived from
-  this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-### myst-parser
-
-The documentation uses [myst-parser](https://github.com/executablebooks/myst-parser), which is under the MIT License:
-
-MIT License
-
-Copyright (c) 2020 ExecutableBookProject
-
-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.
-
-#### Fonts
-
-#####Lato
-
-Copyright (c) 2010-2014, Łukasz Dziedzic (dziedzic@typoland.com),
-with Reserved Font Name Lato.
-
-This Font Software is licensed under the SIL Open Font License, Version 1.1.
-This license is copied below, and is also available with a FAQ at:
-http://scripts.sil.org/OFL
-
-This Font Software is licensed under the SIL Open Font License, Version 1.1.
-This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
-
-#####Open Sans
-
-These fonts are licensed under the Apache License, Version 2.0.
+The `requirements.txt` lists the 3rd party libraries used for the docs.
+For the licenses, see the shared
+[inrupt/docs-assets](https://github.com/inrupt/docs-assets#readme).

docs/api/conf.py

@@ -26,7 +26,7 @@
 # -- product name -----
 # -- Separately update code samples and toc links and docs-navbar since not using substitutions--
 
-name = 'solid-client-notifications API'
+name = 'solid-client-errors API'
 repo_name = '{0}-js'.format(name)
 
 pygments_style = 'sphinx'
@@ -52,7 +52,7 @@
 
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['./_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.
@@ -67,36 +67,67 @@
 #html_theme = 'alabaster'
 
 html_theme = 'inrupt'
-html_theme_path = ['./themes']
+html_theme_path = ['./docs-assets/themes']
 
 html_copy_source = False
 
 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 Documentation'.format(name),
+    'project_title': 'Inrupt {0}'.format(name),
     'banner': False,
     'banner_msg': '',
     'robots_index': True,
     'github_editable': False,
     'github_org': 'inrupt',
     'github_repo': repo_name,
     'github_branch': 'main',
-    'ess_docs': 'https://docs.inrupt.com/ess/',
-    'clientlibjs_docs': 'https://docs.inrupt.com/developer-tools/javascript/client-libraries/',
-    'reactsdk_docs': 'https://docs.inrupt.com/developer-tools/javascript/react-sdk',
+    'docs_project': 'developer-tools/api/javascript/solid-client-errors',
+    'show_api_menu': True,
+
+    # below are pydata_sphinx_theme
+    "footer_items": [ "copyright.html"],
+    "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",
+        },
+    ],
+    "favicons": [
+        {
+         "rel": "icon",
+         "sizes": "16x16",
+         "href": "https://docs.inrupt.com/inrupt_stickers_v2-03.png",
+        },
+    ],
 }
 
 # 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 = ['_static']
+html_static_path = ['./docs-assets/_static']
 
 html_sidebars = {
-    '**': ['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' ]

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.0
+myst-parser==0.17.0
+Sphinx==4.4.0

docs/api/source/index.rst

@@ -10,6 +10,5 @@ solid-client API
    :titlesonly:
 
    /modules/**
-   /interfaces/**
    /classes/**