Add custom component display names #933

glebez · 2018-04-10T20:44:50Z

Hey,

here comes my attempt on allowing users to define custom component display names for SG, that was discussed in #195.

Now, the user can define a custom name via a custom @sgDisplayName tag in the doc block, i.e.:

/*
* An example-less button with custom display name.
* @sgDisplayName Push Button 🎉
*/

or by utilising newly introduced updateDocs config option (#868), i.e.:

updateDocs(docs) { 
  if (docs && docs.displayName) { 
    docs.sgDisplayName = _.lowerCase(docs.displayName); 
  } 
  return docs; 
},

Let me know, please, if this is close to what you meant it to be.
Also, some updates to the cookbook/docs will follow after initial review.

Cheers,
G.

sapegin

This is very cool, thank you!

My only concern is the name:

displayName in JS / React is a component name, so it's not very clear what it is.
sg suffix isn't used anywhere else. We sometimes use rsg.
All custom Styleguidist JSDoc tags have no prefixes (ignore, example, public).

I'd choose something like visibleName to clarify that's it's the name visible in the UI.

sapegin · 2018-04-11T07:23:47Z

loaders/utils/getProps.js

+	if (doc.doclets && doc.doclets.sgDisplayName) {
+		doc.sgDisplayName = doc.doclets.sgDisplayName;
+		delete doc.doclets.sgDisplayName;
+		if (doc.tags) {


What's the difference between doclets and tags? Worth adding a comment.

Honestly, I don't know the difference :D I just noticed, that the custom tag gets added both to doclets and tags while parsing, so i decided it's a good idea to remove it from both. I'll investigate a little more on the matter.

After investigating a little, it seems that doclets and tags are a little redundant.
Here's an example of doclet:

{ version: '1.0.1', author: '[Jeremy Gayed](https://github.com/tizmagik)', deprecated: 'Use the [only true button](#button) instead' }

And here's the tags object:

{ version: [ { title: 'version', description: '1.0.1' } ], author: [ { title: 'author', description: '[Jeremy Gayed](https://github.com/tizmagik)' } ], deprecated: [ { title: 'deprecated', description: 'Use the [only true button](#button) instead' } ] }

Seems, it's the same data, structured a little differently. The interesting part, that we are using two different parsers to get those results. So, unless there are some subtle differences that I've missed, we can do some refactoring and let one of those go. But anyway, I think this work is outside of this pull request purpose. Should I file an issue for that?

glebez · 2018-04-12T08:20:58Z

I've noticed that the names of components in sidebar are still not properly updated. Will look into it.

To be used purely for displaying the component name

glebez · 2018-04-12T12:41:23Z

All right, I've changed the name, updated componenstListRenderer, so it uses visibleName as well and threw in some docs. Also, had to rebase because of conflicts with master.

sapegin

The code looks good, just a few tweak for the docs 🦄

sapegin · 2018-04-12T13:45:34Z

docs/Cookbook.md

@@ -25,6 +25,7 @@
 * [How to add fonts from Google Fonts?](#how-to-add-fonts-from-google-fonts)
 * [How to reuse project’s webpack config?](#how-to-reuse-projects-webpack-config)
 * [How to use React Styleguidist with Redux, Relay or Styled Components?](#how-to-use-react-styleguidist-with-redux-relay-or-styled-components)
+* [How to change the names of components displayed in Styleguidist UI?](#how-to-change-the-names-of-components-displayed-in-styleguidist-ui)


Looks like it's not ordered alphabetically.

Hey, it seems that the rest of the items is not ordered alphabetically as well. Should I order them?

Would be super cool! But preferably in a separate PR.

Hey, I finally got to alphabetically ordering the cookbook sections and want to ask: is this really a good idea? In this case, the first entry in the cookbook will be 'Are there any other projects like this?' and it feels that there are more important/useful topics in the cookbook than this... It feels that there can be a benefit in structuring the cookbook, but in some other, more semantic way, like from beginner topics to more advanced stuff or from most frequent requests to more rare/specific.

Let's skip it then ;-) Are you going to change anything else or I can merge it?

All right! Nope, the rest of the changes is in place already, so this one is ready to go 🚢

sapegin · 2018-04-16T12:23:30Z

docs/Cookbook.md

@@ -479,6 +480,29 @@ See in [configuring webpack](Webpack.md#reusing-your-projects-webpack-config).

 See [working with third-party libraries](Thirdparties.md).

+## How to change the names of components displayed in Styleguidist UI?
+
+Often you might want to change your components' names to be displayed differently, for example, for stylistic purposes or to give them a more descriptive names in your styleguide.


Not really often, I'd remove “often” ;-)

sapegin · 2018-04-16T12:26:13Z

docs/Cookbook.md

+
+This can be done by adding [@visibleName](Documenting.md#-visiblename-custom-tag) tag to your component documentation.
+
+In case you want to change components' names in bulk, for example, based on their current name, you can utilize [updateDocs](Configuration.md#updatedocs) configuration option.


utilize → use
configuration → config

sapegin · 2018-04-16T12:27:03Z

docs/Cookbook.md

+
+In case you want to change components' names in bulk, for example, based on their current name, you can utilize [updateDocs](Configuration.md#updatedocs) configuration option.
+
+Here's an example of how this can be achieved:


You could end the previous paragraph with a “:” and remove this one.

sapegin · 2018-04-16T12:28:05Z

docs/Cookbook.md

+module.exports = {
+  updateDocs(docs) {
+    if (docs && docs.displayName) {
+      docs.visibleName = _.lowerCase(docs.displayName)


docs.displayName.toLowerCase()

sapegin · 2018-04-16T12:29:12Z

docs/Documenting.md

@@ -203,6 +204,23 @@ class Button extends React.Component {
 }
 ```

+### @visibleName custom tag


I think this section should be before “Using JSDoc tags”, similar to “Ignoring props”.

sapegin · 2018-04-16T12:29:25Z

docs/Documenting.md

@@ -203,6 +204,23 @@ class Button extends React.Component {
 }
 ```

+### @visibleName custom tag
+
+Apart from most of the jsDocs tags that can be used with RSG, @visibleName is not present in jsDoc specs. This is a custom tag, that we have added to provide users with a way to define names for components to be used in the UI.


Something like this would be shorter with the same amount of useful information:

Use @visibleName JSDoc tag to define component names that are used in the Styleguidist UI:

(And you could remove the next paragraph too.)

sapegin · 2018-04-16T12:33:32Z

docs/Documenting.md

+class Button extends React.Component {
+```
+
+By defining the @visibleName tag above, you let the Styleguidist know that this name should be used whenever the component is displayed in the UI as 'The Best Button Ever 🐙' instead of it's original 'Button' name.


Instead of repeating what you say in the first paragraph it would be useful to say that this won't change the actual name of the component that is used in JSX.

lukashala · 2018-06-26T13:50:03Z

Is it possible to merge this PR please? These changes would be beneficial in our project. Thx.

reznord

@glebez, thanks for the PR 🎉, this is very cool 😄

@sapegin these changes look good to me! We can go ahead and merge this.

codecov-io · 2018-07-18T11:49:12Z

Codecov Report

Merging #933 into master will increase coverage by <.01%.
The diff coverage is 100%.

Impacted Files	Coverage Δ
loaders/utils/getProps.js	`100% <100%> (ø)`	⬆️
src/utils/processComponents.js	`100% <100%> (ø)`	⬆️
...omponents/ComponentsList/ComponentsListRenderer.js	`100% <100%> (ø)`	⬆️
...rc/rsg-components/ReactComponent/ReactComponent.js	`85.18% <100%> (ø)`	⬆️

sapegin · 2018-07-18T11:51:50Z

Looks like I forget to include this PR in 7.1.0, sorry 😭 — will try to make 7.2.0 soon!

## New features * Add custom component display names ([#933](#933)) ``` module.exports = { updateDocs(docs) { if (docs && docs.displayName) { docs.visibleName = docs.displayName.toLowerCase() } return docs } } ``` * Made the mounting point id configurable. ([#1050](#1050))

## New features * Add custom component display names ([#933](#933)) ``` module.exports = { updateDocs(docs) { if (docs && docs.displayName) { docs.visibleName = docs.displayName.toLowerCase() } return docs } } ``` * Made the mounting point id configurable. ([#1050](#1050)) ## Bug fixes * Cypress failing test ([#1077](#1077))

styleguidist-bot · 2018-08-07T17:31:16Z

🎉 This PR is included in version 7.2.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

- User can define a custom name via a custom @sgDisplayName tag in the doc block

## New features * Add custom component display names ([#933](styleguidist/react-styleguidist#933)) ``` module.exports = { updateDocs(docs) { if (docs && docs.displayName) { docs.visibleName = docs.displayName.toLowerCase() } return docs } } ``` * Made the mounting point id configurable. ([#1050](styleguidist/react-styleguidist#1050))

## New features * Add custom component display names ([#933](styleguidist/react-styleguidist#933)) ``` module.exports = { updateDocs(docs) { if (docs && docs.displayName) { docs.visibleName = docs.displayName.toLowerCase() } return docs } } ``` * Made the mounting point id configurable. ([#1050](styleguidist/react-styleguidist#1050)) ## Bug fixes * Cypress failing test ([#1077](styleguidist/react-styleguidist#1077))

glebez changed the title ~~Feature/custom component display names~~ Add custom component display names Apr 10, 2018

sapegin requested changes Apr 11, 2018

View reviewed changes

glebez added 6 commits April 12, 2018 14:34

create new sgDisplayName property on the component

afd9087

To be used purely for displaying the component name

populate sgDisplayName from custom doc tag

bb0f4d1

bring tests up to speed with new sgDisplayName

5489de3

rename sgDisplayName to visibleName

b1dfa68

change componentsList to use visibleName instead of name

285e26d

add docs and cookbook example on visibleName tag

aab4795

glebez force-pushed the feature/custom-component-display-names branch from b89cdda to aab4795 Compare April 12, 2018 12:38

sapegin requested changes Apr 16, 2018

View reviewed changes

update docs based on feedback

0eda54d

sapegin approved these changes May 2, 2018

View reviewed changes

sapegin added this to the 7.1.0 milestone May 2, 2018

reznord approved these changes Jul 5, 2018

View reviewed changes

sapegin and others added 3 commits July 6, 2018 15:18

Merge branch 'master' into feature/custom-component-display-names

c7ddec9

Update snapshot

ffcab5f

Merge branch 'master' into feature/custom-component-display-names

745966d

sapegin modified the milestones: 7.1.0, 7.2.0 Jul 18, 2018

bluetidepro merged commit b523c45 into styleguidist:master Aug 7, 2018

sapegin mentioned this pull request Aug 8, 2018

Components section names not showing in sidebar (v7.2.0) #1078

Closed

sapegin pushed a commit that referenced this pull request Aug 9, 2018

Feat: Add custom component display names (#933)

c32afc4

- User can define a custom name via a custom @sgDisplayName tag in the doc block

sapegin mentioned this pull request Aug 30, 2018

Improve single-component usage #195

Open

5 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add custom component display names #933

Add custom component display names #933

glebez commented Apr 10, 2018

sapegin left a comment

sapegin Apr 11, 2018

glebez Apr 11, 2018

glebez Apr 12, 2018

glebez commented Apr 12, 2018

glebez commented Apr 12, 2018

sapegin left a comment

sapegin Apr 12, 2018

glebez Apr 20, 2018

sapegin Apr 20, 2018

glebez Apr 20, 2018

glebez May 1, 2018

sapegin May 2, 2018

glebez May 2, 2018

sapegin Apr 16, 2018

sapegin Apr 16, 2018

sapegin Apr 16, 2018

sapegin Apr 16, 2018

sapegin Apr 16, 2018

sapegin Apr 16, 2018

sapegin Apr 16, 2018

lukashala commented Jun 26, 2018

reznord left a comment

codecov-io commented Jul 18, 2018 •

edited

Loading

sapegin commented Jul 18, 2018

styleguidist-bot commented Aug 7, 2018


		This can be done by adding [@visibleName](Documenting.md#-visiblename-custom-tag) tag to your component documentation.

		In case you want to change components' names in bulk, for example, based on their current name, you can utilize [updateDocs](Configuration.md#updatedocs) configuration option.


		In case you want to change components' names in bulk, for example, based on their current name, you can utilize [updateDocs](Configuration.md#updatedocs) configuration option.

		Here's an example of how this can be achieved:

Add custom component display names #933

Add custom component display names #933

Conversation

glebez commented Apr 10, 2018

sapegin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

glebez commented Apr 12, 2018

glebez commented Apr 12, 2018

sapegin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lukashala commented Jun 26, 2018

reznord left a comment

Choose a reason for hiding this comment

codecov-io commented Jul 18, 2018 • edited Loading

Codecov Report

sapegin commented Jul 18, 2018

styleguidist-bot commented Aug 7, 2018

codecov-io commented Jul 18, 2018 •

edited

Loading