This is a guide to generate documentation of the UI components automatically.
Initially when this workflow was not present, the entire documentation of the website was done by editing the docs manually by going to the
docs directory under
website and editing the markdown manually. Now, we have come with a flow where developers and contributors can focus more on logic than on writing markdown.
To do this we have created scripts which would parse the components and generate documentation out of it.
This is a 2 step process:
We take use of
react-docgen-typescriptwhich takes the input of the files for which we want to generate the documentation automatically. This gives in JSON as output. This JSON consists of all the details of the props including
defaultValueand well as
descriptionof the components.
As we use Docusaurus for our documentation website, the pages of the documentation should be in the format of Markdown. Therefore, there should be process where we can change the JSON data, which we get from
react-docgen-typescriptto a suitable Markdown format. For this we use,
json2mdwhich takes in the data and convert it to suitable markdown string. This is stored in the directory and is shown on the website.
Well to make the script to work automatically what we have done is as follows:
When you push your changes to your branch. A script
This invokes the
yarn docs:buildcommand which calls the scripts of auto-generation of docs and this also lints the markdown files generated at the same time.
Now, if there is any changes in the markdown files. A commit with message
Update Documentationis done and pushed after your commit is done to the branch.
Note: By passing pre-push hook will result in failure of documentation update and may lead maintainers to close your PR.
This is simple. Adding, removing, updating the props is also simple now. You just need to update the comments/description of the component and deal with the logic of your React Components(if required). Our workflow will automatically detect the markdown changes if any and push the changes using
pre-push hooks while you push your code to your branch.
Make sure to add appropriate comments and description related to the components and the props of the component. Try keeping your code simple with simpler types for Autogen to work.
Please note: The file name of the component as well as the folder must be in Capital letter. We use
regex to parse the file paths, so this is important.
Note: If there are complex types/defaultValue, please head to
website/scripts/docgen/docgenParser.ts to deal with those cases. Although we recommend you to avoid it as far as possible. Try improving the React logic and that will work.
The demos can now be added by moving in to the
usage directory under
website/docs/main directory. We now have added Snack Player so that you get the glimpse of the component and also get to know how it works. Under the
usage, there is a separate folder for each UI Component, where you can add Usage related to component and relevant descriptions.
Note: To add Snack demo, add it inside the snack directory. You can add as many Snack which will make our repository more helpful for developers.
For testing the changes in the documentation autogeneration, we simply need to run the following commands in sequence.
cd websiteyarn test
We have also included the changes in the main test process, so this will automatically run with the workflow as well as when you run the
yarn test command from root of the project.
Some of the components are class-based. They are: Input, SearchBar, Rating.(from https://github.com/Monte9/react-native-ratings). If you change the components to Functional/hooks based please remove it from the array of
website/scripts/docgen/getComponentFiles.ts. These are the paths of the component files for which the process is still manual.
So, generating the documentation doesn't come up well for these components. Due to the existing structure
react-docgen-typescript fails to generate relevant result for them. We are therefore looking for contributions on these components to make them Fuctional/Hooks based.
Thanks. Hope you like the new workflow. Looking forward for improvements and contributions to it.