Generate Documentation in JS / TS

[AndrewKarasek]

Is there anyway to declare documentation for components in JS (or TS) rather than markdown?

Having free-text (md) feels quite chaotic - writing the documentation in JS would enable us to do linting, import & share stub data, testing and have typesafety in TS.

[sapegin]

You can do most of that in Markdown as well:

• linting — eslint-plugin-markdown;
• import & share stub data — require is supported in Markdown examples);
• testing — snapguidist.

The only thing is missed is TypeScript support. But even this maybe not very hard to implement if anyone wants to have it.

Markdown has many other benefits in my opinion, but if you want to use JavaScript, you probably will like Storybook more than Styleguidist.

[AndrewKarasek]

@sapegin yeah TS support is probably the biggest loss. Being tied to extra dependencies and frameworks is not ideal and taking devs out of their familiar environment (ts / js) to work in free text doesn't sound like the best way to go for us.

Unfortunately storybook doesn't fit our use case for a number of other reasons.

If we forked the repo and developed the option to declare docs in code would that be considered for merging into the main repo? Cheers!

[sapegin]

This may be a good addition of course if it has a good API and won’t complicate the code much ;-)

Do you already have any ideas on the API? Can we somehow reuse it for interoperability with Storybook? (That would be amazing feature!)

[AndrewKarasek]

I'll need to dig into it a bit but my gut thought is to just use a naming scheme to find the documentation and then just some react components to wrap the necessary pieces of documentation. For example:

Filename: Button.doc.js

import * as React from 'react';
import { Section, Copy, RenderedComponent } from 'react-styleguidist';
import MyButton from './MyButton';

import * as React from 'react';
import { Section, Copy, RenderedComponent } from 'react-styleguidist';
import MyButton from './MyButton';

export default () => {
  return (
    <Section>
      <Copy>
        Here I write some assocatiated copy for my component
      </Copy>
      <RenderedComponent>
        {/* 
          everything inside rendered component will get rendered in
          an editable sandbox
        */}
        <MyButton />
      </RenderedComponent>
    </Section>
  );
};

[sapegin]

I’d propose a different approach: decouple current Markdown parsing logic and create a common format fur examples that Styleguidist will use internally. So we could create different “loaders” for Markdown, Storybook and something that you want.

So I’d rewrite you example like this:

import * as React from 'react';
import MyButton from './MyButton';

export default () => {
  return [
       'Here I write some assocatiated copy for my component',
       <MyButton />,
      {
        type: 'example',
        options: { static: true },
        code: <MyButton />
      }
  ];
};

The first two are shortcuts to the full form in the last example.

[dziamid]

Markdown has many other benefits in my opinion

@sapegin what are the benefits?

[sapegin]

• You can structure documentation as you like;
• you can mix examples with text to better explain them;
• you can decide how to render each example: with or without an editor, as static code, etc.
• readable on GitHub or in an editor.

[Jayphen]

@AndrewKarasek

If we forked the repo and developed the option to declare docs in code would that be considered for merging into the main repo? Cheers!

Did you end up creating this fork? I have been trying a styleguide-first approach to development, but the missing type safety and other editor features makes it more difficult than it could be.

[Chr1stian]

Now that the js and jsx tags are supported in Markdown, is it possible to also get a tsx tag?

[elevatebart]

@Chr1stian in order to make tsx available, we need to find a way to transpile it to evaluable javascript. I believe the ts compiler would do the job, but it is incredibly heavy.

I like the idea and might investigate.

[sapegin]

@elevatebart Making compilers customizable would be a great feature and like not hard to implement as soon as we find a good API. The difficulty here is that it's not just Buble (which we need to change to Babel anyway) but also things like transpiling imports and wrapping code in a Fragment. All this should be customizable but at the same time easy to reuse. So extracting them to separate packages might be a good idea ;-)

[sapegin]

By the way for loading TypeScript a Babel plugin might be enough if it's smaller.

[elevatebart]

Here is a couple of links for inspiration of a codeSplit compiler that works:

In vue-styleguidist, we precompile examples in the examples loader then load the compiler asynchronously in the component when users make a change to the code.

This would solve in part the weight issue.
What do you think of this approach ?

[sapegin]

This looks very interesting! And we won't need to transpile imports once we use Babel.