[Question] Best way to create a documentation about components

[caioreis]

Hey,

My team and I decided to create a documentation for the components created inside our app. I'm searching for some way to easily do BlazeComponent.listComponents(), and it would be awesome to have access to variables inside the component and list them.

Any ideas on how to do this?

[mitar]

You have BlazeComponent.components which contains all the components. See here.

Which variables are you thinking about? The ReactiveField you attach in onCreated?

[caioreis]

@mitar, it was just an idea, but probably yes. I want to list the atts inside the component. The idea is to generate a page with components and the atts that can be passed/used inside it. As we are a medium size team, we want to have some control about what's on the code. btw, tks for the quick response.

[caioreis]

@mitar, about the BlazeComponent.components, in order to get a component I need to do this:

BlazeComponent.components[""].LoginSteps

Is there any specific reason for [""] ? It works but it feels strange 😄

[mitar]

See explanation here. So you can use that constant instead, so BlazeComponent.components[ComponentsNamespace.COMPONENTS_FIELD].

[mitar]

Feel free to create a pull request with static method on ComponentsNamespace to return all components inside a namespace, and another for all sub-namespaces.

So feel free to organize that code for you to make it work for you.

[mitar]

But are attributes dynamically added after construction of the component?

So, there are multiple things we ca be talking here:

• arguments you pass with {{> component args <arguments>}}
• data context arguments expected by the component
• reactive fields you add to the component in its onCreated

Which one are you using in your project? Which one you care about?

[caioreis]

@mitar, Our idea is this:

Okay, let me check if that component already exists. Nice, it exists. What are the arguments that can be passed into it? All of this without checking the code. We are even training our design team to use this type of documentation. With this it would be possible for them to understand if a component is customisable.

I don't know if I'm dreaming too much, listing the components it's already great for us.

About the PR, we are already working on somethings that will probably become a PR.

[mitar]

BTW, do you know of: https://github.com/peerlibrary/meteor-blaze-components-explorer

My attempt at creating a global component list: http://components-explorer.meteorapp.com/

I never had time to really do it, but my idea was to:

• have a standard way that you include a screenshot of the component
• list all components in a way published on Atmosphere
• the ideas of arguments you are mentioning also sound very good

Probably we should first then define the proposed way to document and pass the arguments.

But besides arguments there is also what helpers you can and should use. So what methods exist on the component. Or do you think that this is internal to the component?

I like how https://github.com/coffeedoc/codo can discover all the symbols. So maybe, depending if you have enough resources, we could develop something really beautiful here.

[caioreis]

But in this case we are talking about internal components right?

I'm thinking that we can do this in 2 different ways. One is something like codo, a external service that creates documentation based on comments and symbols. We use something similar for our Rails API, as you can check here.

The other direction would be an autodiscover function. Based on BlazeComponet.components function I can look for helpers, arguments, reactive fields and generate a clean array of objects as a result. That array can be used to render an interface. Nothing stops to use this method and also use comments to add screenshots, for example.

someting like BlazeComponents.getComponent(foo).methods() would already brake a leg here. We could filter private method (as onRendered) and use the others to create the documents.

For method one we would probably use commander + gulp (our common stack for CLI) to go over the project, find components and generate an output.

Sounds pretty interesting... what do you think?

[caioreis]

As we are going this far, why not list the event binding? (We are defining events on js)

[mitar]

See also: #139

[mitar]

As we are going this far, why not list the event binding? (We are defining events on js)

Isn't this internal to the component? User of a component should not have to know anything about events.