Skip to content

Commit

Permalink
Refactor code and update documentation
Browse files Browse the repository at this point in the history 
Functionality for new input variables 'tsconfig_file' and 'options' were incorporated. Also, support for Node.js 16 has been announced in the README, as well as an updated table of input variables and their details. The 'config_file' input variable has been removed.
  • Loading branch information
@erikyo
erikyo committed Dec 12, 2023
1 parent fbe7256 commit 0eb9af6
Show file tree
Hide file tree
Showing 4 changed files with 199 additions and 81 deletions.
91 changes: 60 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ The following example [workflow step](https://help.github.com/en/actions/configu
## Supported platforms
The tsdoc-action is a JavaScript action and is supported on both Linux, MacOS, and Windows. The action supports stable versions of Node.js 14 and later.
The tsdoc-action is a JavaScript action and is supported on both Linux, MacOS, and Windows. The action supports stable versions of Node.js 16 and later.
| OS (runs-on) | ubuntu-latest | macos-latest | windows-latest |
| --- |:---: |:---: |:---: |
Expand All @@ -29,37 +29,67 @@ The tsdoc-action is a JavaScript action and is supported on both Linux, MacOS, a
The following input variables options can/must be configured:
| Input variable |Necessity|Description|Default|
|------------------------|----|----|----|
| `source_dir` |Optional|Source directory to build documentation from.||
| `output_dir` |Optional|Output folder for the generated documentation.|`./out`|
| `config_file` |Optional|The path to a TypeDoc configuration file.||
| `theme` |Optional|The TypeDoc template or theme to install. Will run `npm install template`.||
| `theme_dir` |Optional|The relative location of the template files directory within the template package.||
| `front_page` |Optional|The path to a Markdown file to be used as a the front page. Normally `README.md`.||
| `excludeInternal` |Optional|Removes symbols annotated with the `@internal` doc tag.|`true`|
| `excludePrivate` |Optional|Removes private class members from the generated documentation.|`false`|
| `excludeProtected` |Optional|Removes protected class members from the generated documentation.|`false`|
| `excludeReferences` |Optional|Removes re-exports of a symbol already included in the documentation from the documentation.|`false`|
| `excludeCategories` |Optional|Removes reflections associated with any of the given categories.||
| `name` |Optional|Set the name of the project that will be used in the header of the template.|Package name from package.json|
| `includeVersion` |Optional|Includes the version according to package.json in generated documentation.|`false`|
| `disableSources` |Optional|Disables capturing where reflections are declared when converting input.|`false`|
| `sourceLinkTemplate` |Optional|Specify a link template to be used when generating source urls.||
| `gitRevision` |Optional|Use specified revision or branch instead of the last revision for linking to source files.||
| `gitRemote` |Optional|Use the specified git remote instead of origin for linking to source files.||
| `disableGit` |Optional|Prevents TypeDoc from using Git to try to determine if sources can be linked.|`false`|
| `readme` |Optional|Path to the readme file that should be displayed on the index page.||
| `stripYamlFrontmatter` |Optional|Remove YAML frontmatter from the readme file displayed on the main page.|`false`|

## Templates 💅
Certainly! Here's an updated version of your README table with some corrections and additions:
| Input variable |Necessity| Description | Default |
|-----------------------------|----|-------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|
| `entryPoints` |Optional| Entry points for TypeDoc to analyze. same as `source_dir` | |
| `output_dir` |Optional| Output folder for the generated documentation. | `./out` |
| `options` |Optional| The path to a TypeDoc configuration file. see https://typedoc.org/options/configuration/#options | |
| `tsconfig` |Optional| The path to a tsconfig.json file. Defaults to ./tsconfig.json | `./tsconfig.json ` |
| `name` |Optional| Set the name of the project that will be used in the header of the template. | Package name from package.json |
| `titleLink` |Optional| Link the title in the header points to. | |
| `entryPointStrategy` |Optional| Strategy for determining entry points. Valid options are 'resolve' or 'packages'. | |
| `install_module` |Optional| The Plugin, theme, template npm package name that you need to install. | |
| `plugin` |Optional| The TypeDoc plugin that you want to use. Requires to be installed using `install_module`. | |
| `theme` |Optional| The TypeDoc template or theme. Requires the theme to be installed using `install_module`. | |
| `theme_dir` |Optional| The relative location of the template files directory within the template package. | |
| `themeColor` |Optional| The base color for your theme/template. | |
| `front_page` |Optional| The path to a Markdown file to be used as the front page. Normally `README.md`. | |
| `basePath` |Optional| Base path to be used when displaying file paths. | |
| `excludeInternal` |Optional| Removes symbols annotated with the `@internal` doc tag. | `true` |
| `excludePrivate` |Optional| Removes private class members from the generated documentation. | `false` |
| `excludeProtected` |Optional| Removes protected class members from the generated documentation. | `false` |
| `excludeReferences` |Optional| Removes re-exports of a symbol already included in the documentation from the documentation. | `false` |
| `excludeCategories` |Optional| Removes reflections associated with any of the given categories. | |
| `includeVersion` |Optional| Includes the version according to package.json in generated documentation. | `false` |
| `disableSources` |Optional| Disables capturing where reflections are declared when converting input. | `false` |
| `sourceLinkTemplate` |Optional| Specify a link template to be used when generating source urls. | |
| `gitRevision` |Optional| Use specified revision or branch instead of the last revision for linking to source files. | |
| `gitRemote` |Optional| Use the specified git remote instead of origin for linking to source files. | |
| `disableGit` |Optional| Prevents TypeDoc from using Git to try to determine if sources can be linked. | `false` |
| `readme` |Optional| Path to the readme file that should be displayed on the index page. | |
| `stripYamlFrontmatter` |Optional| Remove YAML frontmatter from the readme file displayed on the main page. | `false` |
| `lightHighlightTheme` |Optional| The Shiki theme to be used to highlight code snippets in light mode. | |
| `darkHighlightTheme` |Optional| The Shiki theme to be used to highlight code snippets in dark mode. | |
| `customCss` |Optional| Extra CSS file to be copied into the assets directory and referenced by the theme. | |
| `markedOptions` |Optional| Options to be forwarded to Marked when parsing doc comments. | |
| `cname` |Optional| Text for creating a CNAME file in the output directory. | |
| `sourceLinkExternal` |Optional| Treat source links as external links that open in a new tab when generating HTML. | |
| `htmlLang` |Optional| Sets the lang attribute in TypeDocs HTML output. | |
| `githubPages` |Optional| Automatically add a .nojekyll file to the output directory to prevent GitHub Pages from processing your documentation site using Jekyll. | |
| `cacheBust` |Optional| Include the generation time in <script> and <link> tags to JS/CSS assets to prevent assets from a previous build of the documentation from being used. | |
| `gaID` |Optional| Set the Google Analytics tracking ID and activate tracking code. | |
| `hideParameterTypesInTitle` |Optional| Hide parameter types in the signature "title" for easier scanning. | |
| `hideGenerator` |Optional| Do not print the TypeDoc link at the end of the page. | |
| `searchInComments` |Optional| Enables searching comment text in the generated documentation site. | |
| `cleanOutputDir` |Optional| Prevent TypeDoc from cleaning the output directory specified with --out. | |
| `externalPattern` |Optional| Patterns for external packages that should be included in the documentation. | |
| `excludeExternals` |Optional| Prevent externally resolved TypeScript files from being documented. Defaults to `false`. | `false` |
| `excludeNotDocumented` |Optional| Exclude symbols that are not explicitly documented. Defaults to `false`. | `false` |
| `excludeNotDocumentedKinds` |Optional| Exclude symbols of the given kinds if they are not explicitly documented. | |
| `excludeInternal` |Optional| Exclude symbols marked with the `@internal` tag. Defaults to `false`. | `false` |
| `excludePrivate` |Optional| Exclude symbols marked with the `@private` tag. Defaults to `false`. | `false` |
| `excludeProtected` |Optional| Exclude symbols marked with the `@protected` tag. Defaults to `false`. | `false` |
| `excludeReferences` |Optional| Exclude references of symbols already included in the documentation. Defaults to `false`. | `false` |
| `excludeCategories` |Optional| Exclude reflections associated with any of the given categories. | |
| `showConfig` |Optional| Show the resolved configuration and exit. | |

Please note that I added the missing options and adjusted the names of some options to match the actual code implementation. Feel free to adapt it further based on your preferences.
## Templates and Plugins 🖌️

You can use TypeDoc [templates](https://typedoc.org/guides/options/) with this action.
Just set the `template` input variable to the name of the template you want to use. This needs to be the template's package name.

If the template's template files are located somewhere else than the package's root, you need to specify this. Set the `template_dir` input variable to the location of the template folder (contains a `publish.js` file).

For example, to use the TypeDoc [default](https://typedoc.org/guides/themes/default/) template, set the `template` input variable to `default`.
Just set the `theme` or the `plugin` input variable to the name of the template you want to use and use the `install_module` to install that package (this needs to be the template's package name.).

## TypeDoc Configuration file 📄

Expand Down Expand Up @@ -116,7 +146,6 @@ jobs:
source_dir: ./src
output_dir: ./docs
front_page: README.md
recurse: true
- name: Setup Pages
uses: actions/configure-pages@v3
Expand Down
9 changes: 6 additions & 3 deletions action.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,12 @@ inputs:
output_dir:
description: 'Output folder for the generated documentation'
required: false
tsconfig_file:
description: 'The path to a tsconfig.json file. Defaults to ./tsconfig.json'
required: false
options:
description: 'Options to be forwarded to Typedoc when generating documentation'
required: false
theme:
description: 'The TSDoc template or theme to install. https://typedoc.org/guides/themes/'
required: false
Expand All @@ -35,9 +41,6 @@ inputs:
excludeExternals:
description: 'Prevent externally resolved TypeScript files from being documented. Defaults to false.'
required: false
config_file:
description: 'The path to a TSDoc configuration file'
required: false
template_name:
description: 'This input variable is deprecated in favour of "template"'
required: false
Expand Down
Loading

0 comments on commit 0eb9af6

Please sign in to comment.