Generate and deploy documentation with Typedoc

[jolierabideau]

This issue was to generate documentation of papi-dts and papi-components and deploy the documentation to Github Pages.

/papi-dts:

• Added a new tsconfig for Typedoc to use that includes papi.d.ts. Was getting an error that I could not use papi.d.ts as an entryPoint for Typedoc because it was not included in the tsconfig.
• Added typedoc.json with options
• Added script npm run build:docs
• Added docs to .gitignore
• Updated the README.md to highlight the important parts of the papi-dts because the documentation contains a lot. Hopefully when the fake imports are renamed the highlighted parts will appear at the top of the list.

/papi-components:

• Fixed errors in four components
• Added typedoc.json with options- entryPointStrategy: expand expands directories into an entry point for each file
• Added script npm run build:docs
• Added docs to all ignores- needed to avoid errors with the js files generated with documentation

publish-docs.yml:

• On each push to main, build documentation and deploy it to github-pages

TODO: Add index file to main dir of github-pages branch so there is a brief landing page.

---

This change is 

[irahopkinson]

great job on this, looks like you have grasped GHAs well. Just one non-blocking comment so feel free to merge without any changes.

Reviewed 23 of 23 files at r1, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @jolierabideau)

---

.github/workflows/publish-docs.yml line 13 at r1 (raw file):

    strategy:
      matrix:

BTW you don't really need a stategy matrix for publishing docs and can just put the node version in directly.

---

lib/papi-dts/tsconfig.docs.json line 2 at r1 (raw file):

{
  "extends": "./tsconfig.json",

FYI well done on extending the orignal file here.

[tjcouch-sil]

Reviewed 7 of 23 files at r1, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @jolierabideau)

---

lib/papi-components/package.json line 34 at r1 (raw file):

    "start": "vite --host --open",
    "build:basic": "tsc && vite build && dts-bundle-generator --config ./dts-bundle-generator.config.ts",
    "build:docs": "npx typedoc",

Note you don't need npx here. npx is a command-line shortcut to run things as if you were running them in a script :) so this could just be typedoc

---

lib/papi-components/typedoc.json line 2 at r1 (raw file):

{
  "entryPoints": ["src"],

I saw that SearchBarProps is now exported from its file but is not re-exported from index.ts, and I was tipped off to something: I think maybe the papi-components type documentation is being generated by scraping the files in the src directory rather than being generated from either index.ts or index.d.ts and only showing what is actually available from the package. I believe SearchBarProps is not accessible in code using this library right now even though it is in the type documentation.

---

lib/papi-dts/README.md line 16 at r1 (raw file):

- `@papi/frontend/react`: React hooks to help interaction between React components and the Papi.
- `@papi/backend`: Papi objects that can be accessed in the backend of the extension.
- `@papi/shared`: Declarations shared between core and extensions

@rolfheij-sil when you make your changes, could you please switch this back to papi-shared-types and also add @papi/core? And maybe mention in the line after this that people can explore other sections to understand the types and such but they need to import types from @papi/core :) thanks!

Sorry, Jolie - we just decided like 20 minutes ago to change @papi/shared back to what it was before. Haha no way for you to know

[jolierabideau]

Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @tjcouch-sil)

---

lib/papi-components/package.json line 34 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

Note you don't need npx here. npx is a command-line shortcut to run things as if you were running them in a script :) so this could just be typedoc

Done in #669

---

lib/papi-components/typedoc.json line 2 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

I saw that SearchBarProps is now exported from its file but is not re-exported from index.ts, and I was tipped off to something: I think maybe the papi-components type documentation is being generated by scraping the files in the src directory rather than being generated from either index.ts or index.d.ts and only showing what is actually available from the package. I believe SearchBarProps is not accessible in code using this library right now even though it is in the type documentation.

I see what you're saying, you are right. I am trying to decide which source is better. If I use index.ts then we don't get the items listed below, if I use dist/index.d.ts then I get all of these. But if they aren't included in index.ts do we want them in the documentation?

\[warning\] GridMenuInfo, defined in ./src/grid-menu.component.tsx, is referenced by GridMenuProps but not included in the documentation.

\[warning\] ScriptureReference, defined in ./src/scripture/scripture.model.ts, is referenced by ScrRefSelectorProps.scrRef but not included in the documentation.

\[warning\] ButtonProps, defined in ./src/button.component.tsx, is referenced by Button.Button.\_\_namedParameters but not included in the documentation.

\[warning\] CheckboxProps, defined in ./src/checkbox.component.tsx, is referenced by Checkbox.Checkbox.\_\_namedParameters but not included in the documentation.

\[warning\] ComboBoxProps, defined in ./src/combo-box.component.tsx, is referenced by ComboBox.ComboBox.\_\_namedParameters but not included in the documentation.

\[warning\] ComboBoxOption, defined in ./src/combo-box.component.tsx, is referenced by ComboBox.ComboBox.T but not included in the documentation.

\[warning\] IconButtonProps, defined in ./src/icon-button.component.tsx, is referenced by IconButton.IconButton.\_\_namedParameters but not included in the documentation.

\[warning\] MenuItemProps, defined in ./src/menu-item.component.tsx, is referenced by MenuItem.MenuItem.props but not included in the documentation.

\[warning\] SearchBarProps, defined in ./src/search-bar.component.tsx, is referenced by SearchBar.SearchBar.\_\_namedParameters but not included in the documentation.

\[warning\] SliderProps, defined in ./src/slider.component.tsx, is referenced by Slider.Slider.\_\_namedParameters but not included in the documentation.

\[warning\] SnackbarProps, defined in ./src/snackbar.component.tsx, is referenced by Snackbar.Snackbar.\_\_namedParameters but not included in the documentation.

\[warning\] SwitchProps, defined in ./src/switch.component.tsx, is referenced by Switch.Switch.\_\_namedParameters but not included in the documentation.

\[warning\] TextFieldProps, defined in ./src/text-field.component.tsx, is referenced by TextField.TextField.\_\_namedParameters but not included in the documentation.

\[warning\] CommandHandler, defined in ./src/menu-item.component.tsx, is referenced by GridMenuProps.\_\_type.commandHandler but not included in the documentation.

\[warning\] MenuItemInfo, defined in ./src/menu-item.component.tsx, is referenced by MenuColumn.\_\_type.items but not included in the documentation.

\[warning\] DataHandler, defined in ./src/toolbar.component.tsx, is referenced by ToolbarProps.\_\_type.dataHandler but not included in the documentation.

[tjcouch-sil]

Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @jolierabideau)

---

lib/papi-components/typedoc.json line 2 at r1 (raw file):

Previously, jolierabideau wrote…

I see what you're saying, you are right. I am trying to decide which source is better. If I use index.ts then we don't get the items listed below, if I use dist/index.d.ts then I get all of these. But if they aren't included in index.ts do we want them in the documentation?

\[warning\] GridMenuInfo, defined in ./src/grid-menu.component.tsx, is referenced by GridMenuProps but not included in the documentation.

\[warning\] ScriptureReference, defined in ./src/scripture/scripture.model.ts, is referenced by ScrRefSelectorProps.scrRef but not included in the documentation.

\[warning\] ButtonProps, defined in ./src/button.component.tsx, is referenced by Button.Button.\_\_namedParameters but not included in the documentation.

\[warning\] CheckboxProps, defined in ./src/checkbox.component.tsx, is referenced by Checkbox.Checkbox.\_\_namedParameters but not included in the documentation.

\[warning\] ComboBoxProps, defined in ./src/combo-box.component.tsx, is referenced by ComboBox.ComboBox.\_\_namedParameters but not included in the documentation.

\[warning\] ComboBoxOption, defined in ./src/combo-box.component.tsx, is referenced by ComboBox.ComboBox.T but not included in the documentation.

\[warning\] IconButtonProps, defined in ./src/icon-button.component.tsx, is referenced by IconButton.IconButton.\_\_namedParameters but not included in the documentation.

\[warning\] MenuItemProps, defined in ./src/menu-item.component.tsx, is referenced by MenuItem.MenuItem.props but not included in the documentation.

\[warning\] SearchBarProps, defined in ./src/search-bar.component.tsx, is referenced by SearchBar.SearchBar.\_\_namedParameters but not included in the documentation.

\[warning\] SliderProps, defined in ./src/slider.component.tsx, is referenced by Slider.Slider.\_\_namedParameters but not included in the documentation.

\[warning\] SnackbarProps, defined in ./src/snackbar.component.tsx, is referenced by Snackbar.Snackbar.\_\_namedParameters but not included in the documentation.

\[warning\] SwitchProps, defined in ./src/switch.component.tsx, is referenced by Switch.Switch.\_\_namedParameters but not included in the documentation.

\[warning\] TextFieldProps, defined in ./src/text-field.component.tsx, is referenced by TextField.TextField.\_\_namedParameters but not included in the documentation.

\[warning\] CommandHandler, defined in ./src/menu-item.component.tsx, is referenced by GridMenuProps.\_\_type.commandHandler but not included in the documentation.

\[warning\] MenuItemInfo, defined in ./src/menu-item.component.tsx, is referenced by MenuColumn.\_\_type.items but not included in the documentation.

\[warning\] DataHandler, defined in ./src/toolbar.component.tsx, is referenced by ToolbarProps.\_\_type.dataHandler but not included in the documentation.

Sorry, I'm not understanding exactly what you're saying, but I think I might know what you mean-ish:

These are valuable warnings because they expose exactly the problem I'm talking about. Maybe some of these are not important to export, but it at least gives us a list of what is missing.

If you are saying these warnings print out when you run against index.d.ts but not when you run against index.ts, I'd say let's run on the index.d.ts. If you're saying these types themselves are included when you run against index.d.ts but not when you run against index.ts, let's run on the index.ts. It's a good thing that the typedoc shows only what we actually expose in our library. We want to be as accurate as possible to show developers what they're getting when they use our stuff.

Side note: I think it would be good to export all of these from index.ts. Would you mind filing an issue for it if you don't mind? Or I guess you can fix it if you'd like, but no pressure; this isn't your problem to fix. Also please mention if you file an issue that it we should probably rename some things to be more understandable (I have no idea what DataHandler is for example).

Thank you for the hard work!!

[jolierabideau]

Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @tjcouch-sil)

---

lib/papi-components/typedoc.json line 2 at r1 (raw file):

Previously, tjcouch-sil (TJ Couch) wrote…

Sorry, I'm not understanding exactly what you're saying, but I think I might know what you mean-ish:

These are valuable warnings because they expose exactly the problem I'm talking about. Maybe some of these are not important to export, but it at least gives us a list of what is missing.

If you are saying these warnings print out when you run against index.d.ts but not when you run against index.ts, I'd say let's run on the index.d.ts. If you're saying these types themselves are included when you run against index.d.ts but not when you run against index.ts, let's run on the index.ts. It's a good thing that the typedoc shows only what we actually expose in our library. We want to be as accurate as possible to show developers what they're getting when they use our stuff.

Side note: I think it would be good to export all of these from index.ts. Would you mind filing an issue for it if you don't mind? Or I guess you can fix it if you'd like, but no pressure; this isn't your problem to fix. Also please mention if you file an issue that it we should probably rename some things to be more understandable (I have no idea what DataHandler is for example).

Thank you for the hard work!!

Yes that's basically what I meant! When I generate documentation with src/index.ts as the entryPoint, I get these warnings and the types are not included. When I generate documentation with dist/index.d.ts as the entryPoint, the types listed in the warnings are included in the documentation. So I will use src/index.ts and create the separate issue!

[jolierabideau]

Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @tjcouch-sil)

---

lib/papi-components/typedoc.json line 2 at r1 (raw file):

Previously, jolierabideau wrote…

Yes that's basically what I meant! When I generate documentation with src/index.ts as the entryPoint, I get these warnings and the types are not included. When I generate documentation with dist/index.d.ts as the entryPoint, the types listed in the warnings are included in the documentation. So I will use src/index.ts and create the separate issue!

Made the changes in #669