kamranayub / gatsby-source-typedoc Goto Github PK

A Gatsby source plugin that uses Typedoc to expose its generated JSON as GraphQL nodes

License: Apache License 2.0

JavaScript 95.87% TypeScript 4.13%

gatsby-source-typedoc's Introduction

gatsby-source-typedoc

A Gatsby plugin that executes Typedoc against TypeScript source files to create GraphQL nodes that contain the TypeDoc generated data structure

Example Usage

# Install the plugin
npm install gatsby-source-typedoc
# Install typedoc as a peer dependency
npm install typedoc -D

In your gatsby-config.js:

module.exports = {
  plugins: [
    {
      resolve: "gatsby-source-typedoc",
      options: {

        // Array of Typescript files to
        // include
        src: [
          `${__dirname}/path/to/index.ts`
        ],

        // Options passed to Typedoc Application
        // Usually corresponds to CLI args directly
        // See: https://typedoc.org/guides/options/
        typedoc: {
          tsconfig: `${__dirname}/path/to/tsconfig.json`
        }
      }
    }
  ]
};

Version Notes

0.23.x

Starting with [email protected] you must use TypeScript 4.6+. See release notes Older versions of Typedoc may throw warnings if you are using TS 4.6+, so for this reason I bumped this package a major version (2.x).

Please use 1.x versions of this package for Typedoc 0.22 or below

0.20.x

Starting with [email protected] you must provide a path to the tsconfig.json file. See release notes. This source plugin supports typedoc versions previous to 0.20 but there are breaking changes to the exported JSON you may need to account for.

In GraphQL now you may do:

{
  typedoc {
    id
    source {
      id
      kind
      name
    }
    internal {
      content
    }
  }
}

The typedoc.internal.content field contains the generated JSON you can use to parse and use in your app. You can optionally use GraphQL to go into the typedoc.source fields but due to the recursive nature of the data structure, this may be more annoying than useful.

Transforming Markdown Symbol Links

Want to be able to transform Typedoc symbol links in Markdown files like [[MyClass]] to link to your Typedoc API docs?

Check out the sister plugin gatsby-remark-typedoc-symbol-links.

How is this being used?

We are using this plugin on excaliburjs.github.io to let us link to symbols dynamically in our documentation.

In theory, you could use this to create an entire Gatsby site for your Typedoc project.

Contributing

I welcome all contributions. Releases are automated through GitHub.

gatsby-source-typedoc's People

Contributors

Stargazers

Watchers

gatsby-source-typedoc's Issues

bug: incompatible with 0.22.7

error Encountered error when executing TypeDoc app.expandInputFiles is not a function


  TypeError:app.expandInputFiles is not a function
  
  - gatsby-node.js:94 Object.exports.sourceNodes
    [excaliburjs.github.io]/[gatsby-source-typedoc]/gatsby-node.js:94:47

https://github.com/excaliburjs/excaliburjs.github.io/runs/4567848998?check_suite_focus=true

The automated release is failing 🚨

🚨 The automated release from the `master` branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you could benefit from your bug fixes and new features.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can resolve this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here is some links that can help you:

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

Cannot push to the Git repository.

semantic-release cannot push the version tag to the branch master on the remote Git repository with URL https://[secure]@github.com/kamranayub/gatsby-source-typedoc.git.

This can be caused by:

a misconfiguration of the repositoryUrl option
the repository being unavailable
or missing push permission for the user configured via the Git credentials on your CI environment

Good luck with your project ✨

Your semantic-release bot 📦🚀

File gatsby-node.js is missing when plugin is installed

When I install the plugin with the commands mentioned in the Example Usage section, the directory gatsby-source-typedoc in node_modules looks like this:
-- .eslintrc.json
-- .travis.yml
-- CHANGELOG.md
-- index.js
-- LICENSE
-- package.json
-- README.md

It looks like gatsby-node.js is not installed. Re-installing doesn't help.

Could you verify if gatsby-node.js would be installed?

Support for latest typedoc version

Hi,

first of all, thank you building this nice plugin :)

However, it seems that the latest version of typedoc 0.20.14 is not yet supported. I used the config from your readme and get errors that the "target" and "mode" options are not supported. Also the GraphQL query of typedoc.internal.content just returns a small json string like "{\"id\":0,\"name\":\"my-docs\",\"kind\":0,\"flags\":{},\"originalName\":\"\"} instead of the expected typedoc json.

When I use typedoc 0.17.6 though everything works as expected.

It would be great if the latest version would be supported as well.

This is a clever idea

Nice work!