Explore doc-gen

[tiagoengel]

TL:DR

This expands on the approach we've been using to generate API docs for some packages and add react-docgen to auto generate docs for props.

The main idea is we still generate those in .md format and eventually we can use something like https://docusaurus.io/ (the one facebook uses) or https://docsify.js.org/#/ to create an API docs website, similar to what we have for the native platforms.

Prop docs

There is one big limitation here. react-docgen does not support props that are imported from a different file, and we use that a lot. There is a PR open to add that but it's not looking like this is gonna land anytime soon.

I've used a fork that is based on that PR and supports it, but it is not working for Flow typings, only prop types. This means we will have to to keep documenting and using proptypes if we want to use this.

Other than that it works quite well and we can format the output the way we want, I've used a similar format to what facebook uses in this PR as I think we should follow that.

This is how it looks: https://github.com/Skyscanner/backpack-react-native/blob/4261d6ae3b9737c668a0a403022b7b87c64f933f/docs/bpk-component-chip.md

API docs

Api docs are still using the same approach but using the api directly and not the CLI. We ignore component files as those are documented in the props section.

Going forward

If we think we should move forward with this, we can probably start migrating to this approach, the way I see it we would:

• Add a pre commit hook to auto-generate docs.
• Every time we touch a component we add docs to props and configure it to be auto generated.
• For where to "output" this new information we have two options:
  • Keep it in the same readme file, this means it will be "rendered" in the doc site.
  • Remove the "props" section from the current readme and link to this new file that will live in the docs folder. This will start preparing things to use one of the docs generators mentioned above.
• After we are confident this approach is working well we can configure one of the tools mentioned above to create an API docs site using those readmes and publish to GH pages like we do for the native libs.

Remember to include the following changes:

• [x] UNRELEASED.md
• [x] README.md
• [x] Tests
• [x] Docs (either update backpack-docs now, or create a follow up ticket)

If you are curious about how we review, please read through the code review guidelines

[shaundon]

I like this approach a lot. Some general notes:

---

Every time we touch a component we add docs to props and configure it to be auto generated.

Sounds like a great way to do it.

---

It's unfortunate we have to use a fork but hopefully that can go away some day, if they merge that year-old PR 😅

---

I feel like for now rendering the props on the docs site is preferable to linking people to GitHub. Keeps everything in one place, and sometimes designers can be reluctant to use GitHub. When we get to a stage where our design guidelines are strong enough that designers can get everything they need from the Design tab, we can probably take this further.

[olliecurtis]

Looks good to me I like this approach! I guess the thing to look at would be how we list the files outside of the package.json as it might get a bit cluttered with all our components

[tiagoengel]

Looks good to me I like this approach! I guess the thing to look at would be how we list the files outside of the package.json as it might get a bit cluttered with all our components

Yeah going forward I think we should create a .documentation.config.js or something similar in the root folder just for this, and keep all in there