feat: add react docgen

[KaiVandivier]

Uses React Docgen to parse React components & comments to generate API documentation, which is part of consolidating documentation in the UI library: https://jira.dhis2.org/browse/LIBS-149

There are somethings in the branch currently to help test it out:

1. There are two test build and serve scripts that parse docs from the UI library - if your ui and cli-utils-docsite directories are not siblings, you'll need to change the path
2. There's a link 'React Docs Test' added in the sidebar to view the docs generated by react docgen if you use the serve command

To do before merging:

• Remove test scripts
• Remove React Docs Test in sidebar

[mediremi]

Looks really good 👍

This will probably have to be part of a separate PR since it'll mean changing how we render and style our docs significantly, but it'd be nice if we could set a minimum column width for the generated tables.

For example, here we can see the type column is too wide and description too thin:

Unfortunately markdown does allow specifying column widths, so we'd need to switch to using HTML for rendering these tables. Plus, being able to render shape props multi-line (so {key1: type1\n, key2: type2\n} would also help.

[KaiVandivier]

Yeah it would be nice to have some formatting control over the tables!

I thought newlines weren't possibly inside of the markdown tables, but I just learned that <br/> tags work 👍 I'll see about formatting objects better

[Mohammer5]

I think support for line breaks could be quite useful:

Or maybe we could render code in comments that's wrapped with backticks in a pre tag?
Some of the descriptions are not really readable as the nesting is not obvious.

---

There are some docs for internals being generated.

I'm wondering if there's a way to only generate react docs for the components exported by the UI library.
But I don't think it's going to be an easy task to keep that generic enough to be useful in other cases too?

[KaiVandivier]

So due to the limitations of markdown tables, I don't think supporting newlines is going to work without being able to control the size of columns:

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way. If you can think of a smart way to do it I'm open to it! I think this iteration is "good enough" though since it's searchable, and there might be some utility for developers to getting the internals' APIs too. Hopefully some other context cues will point to what's exported as well, like component and prop type descriptions.

Also, just a reminder that for the UI library, this will be supplement to the storybook, and the storybook should probably get more attention ultimately

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

[KaiVandivier]

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way

Maybe the script takes a path/glob to one or more files that export components (index.js-type files), then only finds and parses the components that are exported from those? 🤔 That algorithm would need to be able to crawl through several files if components are reexported multiple times

[Mohammer5]

think this iteration is "good enough" though since it's searchable

Agreed, you can merge it when you think this PR is ready

---

If you can think of a smart way to do it I'm open to it

The command could expect a path / paths to javascript files and only generate the docs for the functions/components exported from these files (e. g. ./components/*/src/index.js). I guess the script would have to follow the imports until the component definition has been found, but that shouldn't be too hard

[Mohammer5]

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

Ah, that's quite neat! Will add

[KaiVandivier]

@mediremi@Mohammer5 I switched the format to HTML tables which is a nice improvement, and parsing prop descriptions as multiline markdown is now supported: 🎉

• defaultValue items can also be multiline blocks too
• The column widths are pretty good already without needing to specify widths, but there's one in the UI library that still has a slightly skinny 'description' column relative to the other columns in the table. It's still better than the screenshots you guys posted above though!
• Formatting PropTypes.shape() types over multiple lines is pretty tricky and I haven't found a great way to do it without my own pretty printing logic. Luckily all the shape props in the UI library are pretty simple with no nesting and few properties, so hopefully single-line shapes are good enough

[mediremi]

Nice that's already a big improvement 💪

On my screen + font combo things are still a bit squished so I've tried making some changes here: https://github.com/dhis2/cli-utils-docsite/compare/feat-add-react-docgen...feat-add-react-docgen-proposals?expand=1

The main difference is that the 'required' column has been removed and instead an asterisk is shown next to the property name, and custom prop types are rendered using their name if longer than 20 characters.

[Mohammer5]

🎉 That looks a lot better!

[dhis2-bot]

🎉 This PR is included in version 3.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[KaiVandivier]

Uses React Docgen to parse React components & comments to generate API documentation, which is part of consolidating documentation in the UI library: https://jira.dhis2.org/browse/LIBS-149

There are somethings in the branch currently to help test it out:

1. There are two test build and serve scripts that parse docs from the UI library - if your ui and cli-utils-docsite directories are not siblings, you'll need to change the path
2. There's a link 'React Docs Test' added in the sidebar to view the docs generated by react docgen if you use the serve command

To do before merging:

• Remove test scripts
• Remove React Docs Test in sidebar

[mediremi]

Looks really good 👍

This will probably have to be part of a separate PR since it'll mean changing how we render and style our docs significantly, but it'd be nice if we could set a minimum column width for the generated tables.

For example, here we can see the type column is too wide and description too thin:

Unfortunately markdown does allow specifying column widths, so we'd need to switch to using HTML for rendering these tables. Plus, being able to render shape props multi-line (so {key1: type1\n, key2: type2\n} would also help.

[KaiVandivier]

Yeah it would be nice to have some formatting control over the tables!

I thought newlines weren't possibly inside of the markdown tables, but I just learned that <br/> tags work 👍 I'll see about formatting objects better

[Mohammer5]

I think support for line breaks could be quite useful:

Or maybe we could render code in comments that's wrapped with backticks in a pre tag?
Some of the descriptions are not really readable as the nesting is not obvious.

---

There are some docs for internals being generated.

I'm wondering if there's a way to only generate react docs for the components exported by the UI library.
But I don't think it's going to be an easy task to keep that generic enough to be useful in other cases too?

[KaiVandivier]

So due to the limitations of markdown tables, I don't think supporting newlines is going to work without being able to control the size of columns:

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way. If you can think of a smart way to do it I'm open to it! I think this iteration is "good enough" though since it's searchable, and there might be some utility for developers to getting the internals' APIs too. Hopefully some other context cues will point to what's exported as well, like component and prop type descriptions.

Also, just a reminder that for the UI library, this will be supplement to the storybook, and the storybook should probably get more attention ultimately

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

[KaiVandivier]

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way

Maybe the script takes a path/glob to one or more files that export components (index.js-type files), then only finds and parses the components that are exported from those? 🤔 That algorithm would need to be able to crawl through several files if components are reexported multiple times

[Mohammer5]

think this iteration is "good enough" though since it's searchable

Agreed, you can merge it when you think this PR is ready

---

If you can think of a smart way to do it I'm open to it

The command could expect a path / paths to javascript files and only generate the docs for the functions/components exported from these files (e. g. ./components/*/src/index.js). I guess the script would have to follow the imports until the component definition has been found, but that shouldn't be too hard

[Mohammer5]

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

Ah, that's quite neat! Will add

[KaiVandivier]

@mediremi@Mohammer5 I switched the format to HTML tables which is a nice improvement, and parsing prop descriptions as multiline markdown is now supported: 🎉

• defaultValue items can also be multiline blocks too
• The column widths are pretty good already without needing to specify widths, but there's one in the UI library that still has a slightly skinny 'description' column relative to the other columns in the table. It's still better than the screenshots you guys posted above though!
• Formatting PropTypes.shape() types over multiple lines is pretty tricky and I haven't found a great way to do it without my own pretty printing logic. Luckily all the shape props in the UI library are pretty simple with no nesting and few properties, so hopefully single-line shapes are good enough

[mediremi]

Nice that's already a big improvement 💪

On my screen + font combo things are still a bit squished so I've tried making some changes here: https://github.com/dhis2/cli-utils-docsite/compare/feat-add-react-docgen...feat-add-react-docgen-proposals?expand=1

The main difference is that the 'required' column has been removed and instead an asterisk is shown next to the property name, and custom prop types are rendered using their name if longer than 20 characters.

[Mohammer5]

🎉 That looks a lot better!

[dhis2-bot]

🎉 This PR is included in version 3.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[KaiVandivier]

Uses React Docgen to parse React components & comments to generate API documentation, which is part of consolidating documentation in the UI library: https://jira.dhis2.org/browse/LIBS-149

There are somethings in the branch currently to help test it out:

1. There are two test build and serve scripts that parse docs from the UI library - if your ui and cli-utils-docsite directories are not siblings, you'll need to change the path
2. There's a link 'React Docs Test' added in the sidebar to view the docs generated by react docgen if you use the serve command

To do before merging:

• Remove test scripts
• Remove React Docs Test in sidebar

[mediremi]

Looks really good 👍

This will probably have to be part of a separate PR since it'll mean changing how we render and style our docs significantly, but it'd be nice if we could set a minimum column width for the generated tables.

For example, here we can see the type column is too wide and description too thin:

Unfortunately markdown does allow specifying column widths, so we'd need to switch to using HTML for rendering these tables. Plus, being able to render shape props multi-line (so {key1: type1\n, key2: type2\n} would also help.

[KaiVandivier]

Yeah it would be nice to have some formatting control over the tables!

I thought newlines weren't possibly inside of the markdown tables, but I just learned that <br/> tags work 👍 I'll see about formatting objects better

[Mohammer5]

I think support for line breaks could be quite useful:

Or maybe we could render code in comments that's wrapped with backticks in a pre tag?
Some of the descriptions are not really readable as the nesting is not obvious.

---

There are some docs for internals being generated.

I'm wondering if there's a way to only generate react docs for the components exported by the UI library.
But I don't think it's going to be an easy task to keep that generic enough to be useful in other cases too?

[KaiVandivier]

So due to the limitations of markdown tables, I don't think supporting newlines is going to work without being able to control the size of columns:

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way. If you can think of a smart way to do it I'm open to it! I think this iteration is "good enough" though since it's searchable, and there might be some utility for developers to getting the internals' APIs too. Hopefully some other context cues will point to what's exported as well, like component and prop type descriptions.

Also, just a reminder that for the UI library, this will be supplement to the storybook, and the storybook should probably get more attention ultimately

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

[KaiVandivier]

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way

Maybe the script takes a path/glob to one or more files that export components (index.js-type files), then only finds and parses the components that are exported from those? 🤔 That algorithm would need to be able to crawl through several files if components are reexported multiple times

[Mohammer5]

think this iteration is "good enough" though since it's searchable

Agreed, you can merge it when you think this PR is ready

---

If you can think of a smart way to do it I'm open to it

The command could expect a path / paths to javascript files and only generate the docs for the functions/components exported from these files (e. g. ./components/*/src/index.js). I guess the script would have to follow the imports until the component definition has been found, but that shouldn't be too hard

[Mohammer5]

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

Ah, that's quite neat! Will add

[KaiVandivier]

@mediremi@Mohammer5 I switched the format to HTML tables which is a nice improvement, and parsing prop descriptions as multiline markdown is now supported: 🎉

• defaultValue items can also be multiline blocks too
• The column widths are pretty good already without needing to specify widths, but there's one in the UI library that still has a slightly skinny 'description' column relative to the other columns in the table. It's still better than the screenshots you guys posted above though!
• Formatting PropTypes.shape() types over multiple lines is pretty tricky and I haven't found a great way to do it without my own pretty printing logic. Luckily all the shape props in the UI library are pretty simple with no nesting and few properties, so hopefully single-line shapes are good enough

[mediremi]

Nice that's already a big improvement 💪

On my screen + font combo things are still a bit squished so I've tried making some changes here: https://github.com/dhis2/cli-utils-docsite/compare/feat-add-react-docgen...feat-add-react-docgen-proposals?expand=1

The main difference is that the 'required' column has been removed and instead an asterisk is shown next to the property name, and custom prop types are rendered using their name if longer than 20 characters.

[Mohammer5]

🎉 That looks a lot better!

[dhis2-bot]

🎉 This PR is included in version 3.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[KaiVandivier]

Uses React Docgen to parse React components & comments to generate API documentation, which is part of consolidating documentation in the UI library: https://jira.dhis2.org/browse/LIBS-149

There are somethings in the branch currently to help test it out:

1. There are two test build and serve scripts that parse docs from the UI library - if your ui and cli-utils-docsite directories are not siblings, you'll need to change the path
2. There's a link 'React Docs Test' added in the sidebar to view the docs generated by react docgen if you use the serve command

To do before merging:

• Remove test scripts
• Remove React Docs Test in sidebar

[mediremi]

Looks really good 👍

This will probably have to be part of a separate PR since it'll mean changing how we render and style our docs significantly, but it'd be nice if we could set a minimum column width for the generated tables.

For example, here we can see the type column is too wide and description too thin:

Unfortunately markdown does allow specifying column widths, so we'd need to switch to using HTML for rendering these tables. Plus, being able to render shape props multi-line (so {key1: type1\n, key2: type2\n} would also help.

[KaiVandivier]

Yeah it would be nice to have some formatting control over the tables!

I thought newlines weren't possibly inside of the markdown tables, but I just learned that <br/> tags work 👍 I'll see about formatting objects better

[Mohammer5]

I think support for line breaks could be quite useful:

Or maybe we could render code in comments that's wrapped with backticks in a pre tag?
Some of the descriptions are not really readable as the nesting is not obvious.

---

There are some docs for internals being generated.

I'm wondering if there's a way to only generate react docs for the components exported by the UI library.
But I don't think it's going to be an easy task to keep that generic enough to be useful in other cases too?

[KaiVandivier]

So due to the limitations of markdown tables, I don't think supporting newlines is going to work without being able to control the size of columns:

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way. If you can think of a smart way to do it I'm open to it! I think this iteration is "good enough" though since it's searchable, and there might be some utility for developers to getting the internals' APIs too. Hopefully some other context cues will point to what's exported as well, like component and prop type descriptions.

Also, just a reminder that for the UI library, this will be supplement to the storybook, and the storybook should probably get more attention ultimately

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

[KaiVandivier]

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way

Maybe the script takes a path/glob to one or more files that export components (index.js-type files), then only finds and parses the components that are exported from those? 🤔 That algorithm would need to be able to crawl through several files if components are reexported multiple times

[Mohammer5]

think this iteration is "good enough" though since it's searchable

Agreed, you can merge it when you think this PR is ready

---

If you can think of a smart way to do it I'm open to it

The command could expect a path / paths to javascript files and only generate the docs for the functions/components exported from these files (e. g. ./components/*/src/index.js). I guess the script would have to follow the imports until the component definition has been found, but that shouldn't be too hard

[Mohammer5]

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

Ah, that's quite neat! Will add

[KaiVandivier]

@mediremi@Mohammer5 I switched the format to HTML tables which is a nice improvement, and parsing prop descriptions as multiline markdown is now supported: 🎉

• defaultValue items can also be multiline blocks too
• The column widths are pretty good already without needing to specify widths, but there's one in the UI library that still has a slightly skinny 'description' column relative to the other columns in the table. It's still better than the screenshots you guys posted above though!
• Formatting PropTypes.shape() types over multiple lines is pretty tricky and I haven't found a great way to do it without my own pretty printing logic. Luckily all the shape props in the UI library are pretty simple with no nesting and few properties, so hopefully single-line shapes are good enough

[mediremi]

Nice that's already a big improvement 💪

On my screen + font combo things are still a bit squished so I've tried making some changes here: https://github.com/dhis2/cli-utils-docsite/compare/feat-add-react-docgen...feat-add-react-docgen-proposals?expand=1

The main difference is that the 'required' column has been removed and instead an asterisk is shown next to the property name, and custom prop types are rendered using their name if longer than 20 characters.

[Mohammer5]

🎉 That looks a lot better!

[dhis2-bot]

🎉 This PR is included in version 3.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[KaiVandivier]

Uses React Docgen to parse React components & comments to generate API documentation, which is part of consolidating documentation in the UI library: https://jira.dhis2.org/browse/LIBS-149

There are somethings in the branch currently to help test it out:

1. There are two test build and serve scripts that parse docs from the UI library - if your ui and cli-utils-docsite directories are not siblings, you'll need to change the path
2. There's a link 'React Docs Test' added in the sidebar to view the docs generated by react docgen if you use the serve command

To do before merging:

• Remove test scripts
• Remove React Docs Test in sidebar

[mediremi]

Looks really good 👍

This will probably have to be part of a separate PR since it'll mean changing how we render and style our docs significantly, but it'd be nice if we could set a minimum column width for the generated tables.

For example, here we can see the type column is too wide and description too thin:

Unfortunately markdown does allow specifying column widths, so we'd need to switch to using HTML for rendering these tables. Plus, being able to render shape props multi-line (so {key1: type1\n, key2: type2\n} would also help.

[KaiVandivier]

Yeah it would be nice to have some formatting control over the tables!

I thought newlines weren't possibly inside of the markdown tables, but I just learned that <br/> tags work 👍 I'll see about formatting objects better

[Mohammer5]

I think support for line breaks could be quite useful:

Or maybe we could render code in comments that's wrapped with backticks in a pre tag?
Some of the descriptions are not really readable as the nesting is not obvious.

---

There are some docs for internals being generated.

I'm wondering if there's a way to only generate react docs for the components exported by the UI library.
But I don't think it's going to be an easy task to keep that generic enough to be useful in other cases too?

[KaiVandivier]

So due to the limitations of markdown tables, I don't think supporting newlines is going to work without being able to control the size of columns:

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way. If you can think of a smart way to do it I'm open to it! I think this iteration is "good enough" though since it's searchable, and there might be some utility for developers to getting the internals' APIs too. Hopefully some other context cues will point to what's exported as well, like component and prop type descriptions.

Also, just a reminder that for the UI library, this will be supplement to the storybook, and the storybook should probably get more attention ultimately

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

[KaiVandivier]

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way

Maybe the script takes a path/glob to one or more files that export components (index.js-type files), then only finds and parses the components that are exported from those? 🤔 That algorithm would need to be able to crawl through several files if components are reexported multiple times

[Mohammer5]

think this iteration is "good enough" though since it's searchable

Agreed, you can merge it when you think this PR is ready

---

If you can think of a smart way to do it I'm open to it

The command could expect a path / paths to javascript files and only generate the docs for the functions/components exported from these files (e. g. ./components/*/src/index.js). I guess the script would have to follow the imports until the component definition has been found, but that shouldn't be too hard

[Mohammer5]

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

Ah, that's quite neat! Will add

[KaiVandivier]

@mediremi@Mohammer5 I switched the format to HTML tables which is a nice improvement, and parsing prop descriptions as multiline markdown is now supported: 🎉

• defaultValue items can also be multiline blocks too
• The column widths are pretty good already without needing to specify widths, but there's one in the UI library that still has a slightly skinny 'description' column relative to the other columns in the table. It's still better than the screenshots you guys posted above though!
• Formatting PropTypes.shape() types over multiple lines is pretty tricky and I haven't found a great way to do it without my own pretty printing logic. Luckily all the shape props in the UI library are pretty simple with no nesting and few properties, so hopefully single-line shapes are good enough

[mediremi]

Nice that's already a big improvement 💪

On my screen + font combo things are still a bit squished so I've tried making some changes here: https://github.com/dhis2/cli-utils-docsite/compare/feat-add-react-docgen...feat-add-react-docgen-proposals?expand=1

The main difference is that the 'required' column has been removed and instead an asterisk is shown next to the property name, and custom prop types are rendered using their name if longer than 20 characters.

[Mohammer5]

🎉 That looks a lot better!

[dhis2-bot]

🎉 This PR is included in version 3.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[KaiVandivier]

Uses React Docgen to parse React components & comments to generate API documentation, which is part of consolidating documentation in the UI library: https://jira.dhis2.org/browse/LIBS-149

There are somethings in the branch currently to help test it out:

1. There are two test build and serve scripts that parse docs from the UI library - if your ui and cli-utils-docsite directories are not siblings, you'll need to change the path
2. There's a link 'React Docs Test' added in the sidebar to view the docs generated by react docgen if you use the serve command

To do before merging:

• Remove test scripts
• Remove React Docs Test in sidebar

[mediremi]

Looks really good 👍

This will probably have to be part of a separate PR since it'll mean changing how we render and style our docs significantly, but it'd be nice if we could set a minimum column width for the generated tables.

For example, here we can see the type column is too wide and description too thin:

Unfortunately markdown does allow specifying column widths, so we'd need to switch to using HTML for rendering these tables. Plus, being able to render shape props multi-line (so {key1: type1\n, key2: type2\n} would also help.

[KaiVandivier]

Yeah it would be nice to have some formatting control over the tables!

I thought newlines weren't possibly inside of the markdown tables, but I just learned that <br/> tags work 👍 I'll see about formatting objects better

[Mohammer5]

I think support for line breaks could be quite useful:

Or maybe we could render code in comments that's wrapped with backticks in a pre tag?
Some of the descriptions are not really readable as the nesting is not obvious.

---

There are some docs for internals being generated.

I'm wondering if there's a way to only generate react docs for the components exported by the UI library.
But I don't think it's going to be an easy task to keep that generic enough to be useful in other cases too?

[KaiVandivier]

So due to the limitations of markdown tables, I don't think supporting newlines is going to work without being able to control the size of columns:

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way. If you can think of a smart way to do it I'm open to it! I think this iteration is "good enough" though since it's searchable, and there might be some utility for developers to getting the internals' APIs too. Hopefully some other context cues will point to what's exported as well, like component and prop type descriptions.

Also, just a reminder that for the UI library, this will be supplement to the storybook, and the storybook should probably get more attention ultimately

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

[KaiVandivier]

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way

Maybe the script takes a path/glob to one or more files that export components (index.js-type files), then only finds and parses the components that are exported from those? 🤔 That algorithm would need to be able to crawl through several files if components are reexported multiple times

[Mohammer5]

think this iteration is "good enough" though since it's searchable

Agreed, you can merge it when you think this PR is ready

---

If you can think of a smart way to do it I'm open to it

The command could expect a path / paths to javascript files and only generate the docs for the functions/components exported from these files (e. g. ./components/*/src/index.js). I guess the script would have to follow the imports until the component definition has been found, but that shouldn't be too hard

[Mohammer5]

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

Ah, that's quite neat! Will add

[KaiVandivier]

@mediremi@Mohammer5 I switched the format to HTML tables which is a nice improvement, and parsing prop descriptions as multiline markdown is now supported: 🎉

• defaultValue items can also be multiline blocks too
• The column widths are pretty good already without needing to specify widths, but there's one in the UI library that still has a slightly skinny 'description' column relative to the other columns in the table. It's still better than the screenshots you guys posted above though!
• Formatting PropTypes.shape() types over multiple lines is pretty tricky and I haven't found a great way to do it without my own pretty printing logic. Luckily all the shape props in the UI library are pretty simple with no nesting and few properties, so hopefully single-line shapes are good enough

[mediremi]

Nice that's already a big improvement 💪

On my screen + font combo things are still a bit squished so I've tried making some changes here: https://github.com/dhis2/cli-utils-docsite/compare/feat-add-react-docgen...feat-add-react-docgen-proposals?expand=1

The main difference is that the 'required' column has been removed and instead an asterisk is shown next to the property name, and custom prop types are rendered using their name if longer than 20 characters.

[Mohammer5]

🎉 That looks a lot better!

[dhis2-bot]

🎉 This PR is included in version 3.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[KaiVandivier]

Uses React Docgen to parse React components & comments to generate API documentation, which is part of consolidating documentation in the UI library: https://jira.dhis2.org/browse/LIBS-149

There are somethings in the branch currently to help test it out:

1. There are two test build and serve scripts that parse docs from the UI library - if your ui and cli-utils-docsite directories are not siblings, you'll need to change the path
2. There's a link 'React Docs Test' added in the sidebar to view the docs generated by react docgen if you use the serve command

To do before merging:

• Remove test scripts
• Remove React Docs Test in sidebar

[mediremi]

Looks really good 👍

This will probably have to be part of a separate PR since it'll mean changing how we render and style our docs significantly, but it'd be nice if we could set a minimum column width for the generated tables.

For example, here we can see the type column is too wide and description too thin:

Unfortunately markdown does allow specifying column widths, so we'd need to switch to using HTML for rendering these tables. Plus, being able to render shape props multi-line (so {key1: type1\n, key2: type2\n} would also help.

[KaiVandivier]

Yeah it would be nice to have some formatting control over the tables!

I thought newlines weren't possibly inside of the markdown tables, but I just learned that <br/> tags work 👍 I'll see about formatting objects better

[Mohammer5]

I think support for line breaks could be quite useful:

Or maybe we could render code in comments that's wrapped with backticks in a pre tag?
Some of the descriptions are not really readable as the nesting is not obvious.

---

There are some docs for internals being generated.

I'm wondering if there's a way to only generate react docs for the components exported by the UI library.
But I don't think it's going to be an easy task to keep that generic enough to be useful in other cases too?

[KaiVandivier]

So due to the limitations of markdown tables, I don't think supporting newlines is going to work without being able to control the size of columns:

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way. If you can think of a smart way to do it I'm open to it! I think this iteration is "good enough" though since it's searchable, and there might be some utility for developers to getting the internals' APIs too. Hopefully some other context cues will point to what's exported as well, like component and prop type descriptions.

Also, just a reminder that for the UI library, this will be supplement to the storybook, and the storybook should probably get more attention ultimately

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

[KaiVandivier]

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way

Maybe the script takes a path/glob to one or more files that export components (index.js-type files), then only finds and parses the components that are exported from those? 🤔 That algorithm would need to be able to crawl through several files if components are reexported multiple times

[Mohammer5]

think this iteration is "good enough" though since it's searchable

Agreed, you can merge it when you think this PR is ready

---

If you can think of a smart way to do it I'm open to it

The command could expect a path / paths to javascript files and only generate the docs for the functions/components exported from these files (e. g. ./components/*/src/index.js). I guess the script would have to follow the imports until the component definition has been found, but that shouldn't be too hard

[Mohammer5]

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

Ah, that's quite neat! Will add

[KaiVandivier]

@mediremi@Mohammer5 I switched the format to HTML tables which is a nice improvement, and parsing prop descriptions as multiline markdown is now supported: 🎉

• defaultValue items can also be multiline blocks too
• The column widths are pretty good already without needing to specify widths, but there's one in the UI library that still has a slightly skinny 'description' column relative to the other columns in the table. It's still better than the screenshots you guys posted above though!
• Formatting PropTypes.shape() types over multiple lines is pretty tricky and I haven't found a great way to do it without my own pretty printing logic. Luckily all the shape props in the UI library are pretty simple with no nesting and few properties, so hopefully single-line shapes are good enough

[mediremi]

Nice that's already a big improvement 💪

On my screen + font combo things are still a bit squished so I've tried making some changes here: https://github.com/dhis2/cli-utils-docsite/compare/feat-add-react-docgen...feat-add-react-docgen-proposals?expand=1

The main difference is that the 'required' column has been removed and instead an asterisk is shown next to the property name, and custom prop types are rendered using their name if longer than 20 characters.

[Mohammer5]

🎉 That looks a lot better!

[dhis2-bot]

🎉 This PR is included in version 3.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[KaiVandivier]

Uses React Docgen to parse React components & comments to generate API documentation, which is part of consolidating documentation in the UI library: https://jira.dhis2.org/browse/LIBS-149

There are somethings in the branch currently to help test it out:

1. There are two test build and serve scripts that parse docs from the UI library - if your ui and cli-utils-docsite directories are not siblings, you'll need to change the path
2. There's a link 'React Docs Test' added in the sidebar to view the docs generated by react docgen if you use the serve command

To do before merging:

• Remove test scripts
• Remove React Docs Test in sidebar

[mediremi]

Looks really good 👍

This will probably have to be part of a separate PR since it'll mean changing how we render and style our docs significantly, but it'd be nice if we could set a minimum column width for the generated tables.

For example, here we can see the type column is too wide and description too thin:

Unfortunately markdown does allow specifying column widths, so we'd need to switch to using HTML for rendering these tables. Plus, being able to render shape props multi-line (so {key1: type1\n, key2: type2\n} would also help.

[KaiVandivier]

Yeah it would be nice to have some formatting control over the tables!

I thought newlines weren't possibly inside of the markdown tables, but I just learned that <br/> tags work 👍 I'll see about formatting objects better

[Mohammer5]

I think support for line breaks could be quite useful:

Or maybe we could render code in comments that's wrapped with backticks in a pre tag?
Some of the descriptions are not really readable as the nesting is not obvious.

---

There are some docs for internals being generated.

I'm wondering if there's a way to only generate react docs for the components exported by the UI library.
But I don't think it's going to be an easy task to keep that generic enough to be useful in other cases too?

[KaiVandivier]

So due to the limitations of markdown tables, I don't think supporting newlines is going to work without being able to control the size of columns:

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way. If you can think of a smart way to do it I'm open to it! I think this iteration is "good enough" though since it's searchable, and there might be some utility for developers to getting the internals' APIs too. Hopefully some other context cues will point to what's exported as well, like component and prop type descriptions.

Also, just a reminder that for the UI library, this will be supplement to the storybook, and the storybook should probably get more attention ultimately

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

[KaiVandivier]

I agree it would be nice to only document exported components, but I also agree that's tricky to do in a generalizable way

Maybe the script takes a path/glob to one or more files that export components (index.js-type files), then only finds and parses the components that are exported from those? 🤔 That algorithm would need to be able to crawl through several files if components are reexported multiple times

[Mohammer5]

think this iteration is "good enough" though since it's searchable

Agreed, you can merge it when you think this PR is ready

---

If you can think of a smart way to do it I'm open to it

The command could expect a path / paths to javascript files and only generate the docs for the functions/components exported from these files (e. g. ./components/*/src/index.js). I guess the script would have to follow the imports until the component definition has been found, but that shouldn't be too hard

[Mohammer5]

Related to that, @Mohammer5 maybe that renderNodeLabel can use a function signature annotation? I think Storybook supports that

Ah, that's quite neat! Will add

[KaiVandivier]

@mediremi@Mohammer5 I switched the format to HTML tables which is a nice improvement, and parsing prop descriptions as multiline markdown is now supported: 🎉

• defaultValue items can also be multiline blocks too
• The column widths are pretty good already without needing to specify widths, but there's one in the UI library that still has a slightly skinny 'description' column relative to the other columns in the table. It's still better than the screenshots you guys posted above though!
• Formatting PropTypes.shape() types over multiple lines is pretty tricky and I haven't found a great way to do it without my own pretty printing logic. Luckily all the shape props in the UI library are pretty simple with no nesting and few properties, so hopefully single-line shapes are good enough

[mediremi]

Nice that's already a big improvement 💪

On my screen + font combo things are still a bit squished so I've tried making some changes here: https://github.com/dhis2/cli-utils-docsite/compare/feat-add-react-docgen...feat-add-react-docgen-proposals?expand=1

The main difference is that the 'required' column has been removed and instead an asterisk is shown next to the property name, and custom prop types are rendered using their name if longer than 20 characters.

[Mohammer5]

🎉 That looks a lot better!

[dhis2-bot]

🎉 This PR is included in version 3.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀