Replace esdoc by gaurav · Pull Request #166 · phyloref/phyx.js

gaurav · 2026-03-15T03:59:40Z

We've been using esdoc to generate the phyx.js documentation, and it works well and looks good, but it hasn't been updated in eight years and some of its dependencies have vulnerabilities in them. This PR replaces that with jsdoc, which is in active development. It uses the clean-jsdoc-theme, which has only been defunct for two years, but isn't as ugly or as defunct as the other jsdoc themes I saw.

I also considered jsdoc-fresh, which is brand new but a little ugly.

WIP: Should be merged after PR #167.

The existing tutorials don't work very well in the new template -- I should replace them with a simple Markdown file that links to them in GitHub, or get rid of them entirely.
Deploy new website to https://gaurav.github.io/phyx.js/ so we can compare it with https://phyloref.github.io/phyx.js/

- Replace esdoc (unmaintained, vulnerable) with jsdoc + docdash - Add jsdoc.json config, tutorials/tutorials.json, .github/workflows/docs.yml - Update package.json: new docs scripts (predocs/docs/postdocs), remove esdoc - Move docs/context/ → context/ (repo root) to preserve versioned JSON-LD context and schema files across doc regenerations - postdocs copies context/ back into docs/context/ for GitHub Pages URLs - Update all path references: test/examples.js, 14 test JSON/JSONLD fixtures, tutorials/Introduction.md, tutorials/Introduction.ipynb, test/examples/README.md - Fix invalid JSDoc type expressions in PhyxWrapper.js (function signature syntax, Promise[string] → Promise.<string>) - Exclude context/ from biome linter (like docs/) - Regenerate docs/ with JSDoc/docdash output Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Replaces docdash with clean-jsdoc-theme for better search (Fuse.js full-text), a top nav bar with GitHub and npm links, and Tutorials listed before Classes in the sidebar. File order in source.include controls class ordering; biome formatting applied to jsdoc.json. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

We now have a GitHub Action to generate these on new releases only.

Copilot

Pull request overview

This PR removes committed ESDoc-generated documentation artifacts and introduces a new documentation publishing workflow (JSDoc-based), alongside contributor/release process notes and minor tooling config updates.

Changes:

Removed generated documentation HTML/CSS assets under docs/ (previously produced by ESDoc).
Added a GitHub Actions workflow to generate and publish docs on releases.
Added RELEASE.md and AGENTS.md guidance; updated Biome config to exclude context/.

Reviewed changes

Copilot reviewed 29 out of 112 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
docs/file/src/wrappers/SpecimenWrapper.js.html	Removes committed generated ESDoc HTML output.
docs/file/src/wrappers/PhyxWrapper.js.html	Removes committed generated ESDoc HTML output.
docs/file/src/wrappers/PhylorefWrapper.js.html	Removes committed generated ESDoc HTML output.
docs/file/src/wrappers/PhylogenyWrapper.js.html	Removes committed generated ESDoc HTML output.
docs/file/src/wrappers/CitationWrapper.js.html	Removes committed generated ESDoc HTML output.
docs/file/src/matchers/TaxonomicUnitMatcher.js.html	Removes committed generated ESDoc HTML output.
docs/css/test.css	Removes committed generated docs styling asset.
docs/css/style.css	Removes committed generated docs styling asset.
docs/css/source.css	Removes committed generated docs styling asset.
docs/css/search.css	Removes committed generated docs styling asset.
docs/css/prettify-tomorrow.css	Removes committed generated docs syntax highlighting asset.
docs/css/manual.css	Removes committed generated docs manual styling asset.
docs/css/identifiers.css	Removes committed generated docs styling asset.
docs/css/github.css	Removes committed generated docs styling asset.
docs/coverage.json	Removes committed generated documentation coverage metadata.
docs/class/src/wrappers/TaxonomicUnitWrapper.js~TaxonomicUnitWrapper.html	Removes committed generated ESDoc class documentation.
docs/class/src/wrappers/SpecimenWrapper.js~SpecimenWrapper.html	Removes committed generated ESDoc class documentation.
docs/class/src/wrappers/PhyxWrapper.js~PhyxWrapper.html	Removes committed generated ESDoc class documentation.
docs/class/src/wrappers/CitationWrapper.js~CitationWrapper.html	Removes committed generated ESDoc class documentation.
docs/class/src/matchers/TaxonomicUnitMatcher.js~TaxonomicUnitMatcher.html	Removes committed generated ESDoc class documentation.
biome.json	Excludes `context/` from Biome formatting/linting targets.
RELEASE.md	Adds documented release steps, including docs publishing notes.
AGENTS.md	Adds contributor notes for lint/test/docs workflow.
.github/workflows/docs.yml	Adds automated docs generation + deployment to `gh-pages`.

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

You can also share your feedback on Copilot code review. Take the survey.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

`source.includePattern`, `source.excludePattern`, and `opts.recurse` are no-ops when `source.include` lists only explicit files (no directory scanning occurs). The `templates` block is also unused by clean-jsdoc-theme. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This PR migrates documentation publishing away from committing ESDoc-generated artifacts, moving toward a JSDoc-based docs pipeline published via GitHub Actions to GitHub Pages.

Changes:

Removed committed ESDoc-generated HTML/CSS/coverage artifacts from docs/.
Added a docs.yml GitHub Actions workflow to generate docs and deploy them to the gh-pages branch on release publish (and manual trigger).
Updated repo docs/tooling guidance (AGENTS.md, RELEASE.md) and adjusted Biome file inclusion patterns.

Reviewed changes

Copilot reviewed 29 out of 112 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
docs/file/src/wrappers/SpecimenWrapper.js.html	Removes committed ESDoc-generated source view page.
docs/file/src/wrappers/PhyxWrapper.js.html	Removes committed ESDoc-generated source view page.
docs/file/src/wrappers/PhylorefWrapper.js.html	Removes committed ESDoc-generated source view page.
docs/file/src/wrappers/PhylogenyWrapper.js.html	Removes committed ESDoc-generated source view page.
docs/file/src/wrappers/CitationWrapper.js.html	Removes committed ESDoc-generated source view page.
docs/file/src/matchers/TaxonomicUnitMatcher.js.html	Removes committed ESDoc-generated source view page.
docs/css/test.css	Removes committed ESDoc theme CSS asset.
docs/css/style.css	Removes committed ESDoc theme CSS asset.
docs/css/source.css	Removes committed ESDoc theme CSS asset.
docs/css/search.css	Removes committed ESDoc theme CSS asset.
docs/css/prettify-tomorrow.css	Removes committed ESDoc prettify theme CSS asset.
docs/css/manual.css	Removes committed ESDoc manual CSS asset.
docs/css/identifiers.css	Removes committed ESDoc identifiers CSS asset.
docs/css/github.css	Removes committed ESDoc GitHub-markdown CSS asset.
docs/coverage.json	Removes committed ESDoc documentation coverage summary.
docs/class/src/wrappers/TaxonomicUnitWrapper.js~TaxonomicUnitWrapper.html	Removes committed ESDoc-generated API class page.
docs/class/src/wrappers/SpecimenWrapper.js~SpecimenWrapper.html	Removes committed ESDoc-generated API class page.
docs/class/src/wrappers/PhyxWrapper.js~PhyxWrapper.html	Removes committed ESDoc-generated API class page.
docs/class/src/wrappers/CitationWrapper.js~CitationWrapper.html	Removes committed ESDoc-generated API class page.
docs/class/src/matchers/TaxonomicUnitMatcher.js~TaxonomicUnitMatcher.html	Removes committed ESDoc-generated API class page.
biome.json	Updates Biome schema URL and excludes `context/` along with `docs/` from Biome processing.
RELEASE.md	Documents that publishing a release triggers docs publishing workflow.
AGENTS.md	Updates tooling/docs guidance for JSDoc + CI-published docs; advises not committing generated docs.
.github/workflows/docs.yml	Adds a workflow to generate docs and publish to `gh-pages`.

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

Copilot · 2026-04-01T06:59:10Z

+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          publish_branch: gh-pages
+          force_orphan: true


force_orphan: true will recreate the gh-pages branch from scratch on every publish, which can unintentionally delete hand-managed files on gh-pages (e.g., CNAME, robots.txt, custom redirects). If you need to preserve such files, consider removing force_orphan, or configure keep_files/cname (supported by the action) and ensure these assets are generated/copied into docs/ before deployment.

Suggested change

force_orphan: true

Copilot · 2026-04-01T06:59:10Z

@@ -0,0 +1,41 @@
+name: Publish Documentation
+
+on:


This workflow only publishes docs on release.published (or manual runs). Since this PR also removes committed docs/ artifacts from the default branch, GitHub Pages will go stale or break unless the repository’s Pages configuration is switched to serve from the gh-pages branch (or another deployment mechanism is configured). Please confirm/update the GitHub Pages source accordingly as part of this change.

Suggested change

on:

on:

push:

branches:

- main

Copilot · 2026-04-01T06:59:10Z

@@ -1,13 +1,13 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.4/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",


The exclusion globs !docs and !context may not exclude nested files depending on Biome’s glob semantics (some matchers require !docs/** / !context/** to exclude contents). If the intent is to exclude entire directories recursively, update these patterns to explicitly exclude all descendants to avoid Biome unexpectedly formatting/linting files under those directories.

Copilot · 2026-04-01T06:59:11Z

  "files": {
    "ignoreUnknown": false,
-    "includes": ["**/*.js", "**/*.json", "**/*.md", "!docs"]
+    "includes": ["**/*.js", "**/*.json", "**/*.md", "!docs", "!context"]


The exclusion globs !docs and !context may not exclude nested files depending on Biome’s glob semantics (some matchers require !docs/** / !context/** to exclude contents). If the intent is to exclude entire directories recursively, update these patterns to explicitly exclude all descendants to avoid Biome unexpectedly formatting/linting files under those directories.

Suggested change

"includes": ["**/*.js", "**/*.json", "**/*.md", "!docs", "!context"]

"includes": ["**/*.js", "**/*.json", "**/*.md", "!docs/**", "!context/**"]

gaurav and others added 5 commits March 14, 2026 20:32

Deleted cached docs files.

6540617

We now have a GitHub Action to generate these on new releases only.

Claude wrote up an initial version of a release document for phyx.js.

42b2056

AGENTS.md file specific to this branch.

0cb94d6

gaurav requested a review from Copilot March 15, 2026 04:01

Copilot AI reviewed Mar 15, 2026

View reviewed changes

Comment thread .github/workflows/docs.yml

Comment thread RELEASE.md

Comment thread RELEASE.md Outdated

gaurav and others added 3 commits April 1, 2026 02:11

Potential fix for pull request finding

538253c

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Merge branch 'master' into replace-esdoc

7449fcd

Merge branch 'add-agents-md' into replace-esdoc

6cb6be7

gaurav changed the base branch from master to add-agents-md April 1, 2026 06:24

gaurav and others added 6 commits April 1, 2026 02:26

Added /docs to .gitignore.

ac50f48

Upgraded packages with npm upgrade and npx npm-check-updates -u.

38a2cba

Change default theme to dark.

2f544be

Deleted docs/ between runs.

4e794f2

Added .nojekyll to file.

8e80ba4

gaurav requested a review from Copilot April 1, 2026 06:57

Copilot AI reviewed Apr 1, 2026

View reviewed changes

Base automatically changed from add-agents-md to master April 3, 2026 03:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace esdoc#166

Replace esdoc#166
gaurav wants to merge 14 commits intomasterfrom
replace-esdoc

gaurav commented Mar 15, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 1, 2026

Uh oh!

Copilot AI Apr 1, 2026

Uh oh!

Copilot AI Apr 1, 2026

Uh oh!

Copilot AI Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

-on:
+on:
+  push:
+    branches:
+      - main

	"includes": ["*/.js", "*/.json", "*/.md", "!docs", "!context"]
	"includes": ["*/.js", "*/.json", "*/.md", "!docs/", "!context/"]

Conversation

gaurav commented Mar 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

gaurav commented Mar 15, 2026 •

edited

Loading