phyx.js/jsdoc.config.js at master · phyloref/phyx.js · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
/*
 * jsdoc configuration. This is a JS file rather than JSON so that the footer can
 * carry the version being documented: the site is published only when a release
 * is, so every page needs to say which release it describes.
 */

const { execFileSync } = require('node:child_process');
const { version } = require('./package.json');

/*
 * The version to print in the footer.
 *
 * `git describe --tags` answers both of the ways this site gets published. A release run checks
 * out the tag, so it returns exactly `v1.2.1`; a manual run from master returns something like
 * `v1.2.1-138-g2cbb006`, which says how far past the last release the build is instead of
 * claiming to be that release.
 *
 * It needs tags, so .github/workflows/docs.yml checks out with `fetch-depth: 0` -- the default
 * shallow clone has none and this falls back. Falling back is also what happens when there is no
 * git at all, as in an npm tarball. Don't reach for `--always` to avoid the fallback: it
 * "succeeds" outside a tagged history by returning a bare commit hash, which is less use in a
 * footer than the version we already know.
 */
function describeVersion() {
  try {
    return execFileSync('git', ['describe', '--tags'], {
      encoding: 'utf8',
      stdio: ['ignore', 'pipe', 'ignore'],
    }).trim();
  } catch {
    return `v${version}`;
  }
}

module.exports = {
  source: {
    include: ['./src'],
    exclude: ['./src/index.js', './src/utils/owlterms.js'],
    includePattern: '\\.js$',
  },
  opts: {
    destination: './site',
    recurse: true,
    readme: './README.md',
    template: './node_modules/clean-jsdoc-theme/dist',
    tutorials: './tutorials/build/tutorials',
    docs: './tutorials/build/docs',
    defaultDocGroup: 'About',
    siteName: '@phyloref/phyx.js',
    siteUrl: 'https://www.phyloref.org/phyx.js',
    basePath: '/phyx.js',
    strict: true,
    sectionOrder: ['Tutorials', 'Wrappers', 'Matchers', 'Utilities', 'About'],
    menu: [
      {
        title: 'GitHub',
        link: 'https://github.com/phyloref/phyx.js',
      },
      {
        title: 'npm',
        link: 'https://www.npmjs.com/package/@phyloref/phyx',
      },
    ],
    footer: `phyx.js ${describeVersion()} — Phyloreference Exchange (Phyx) format library`,
  },
  tags: {
    allowUnknownTags: ['category'],
  },
  plugins: ['plugins/markdown'],
  markdown: {
    idInHeadings: true,
  },
};