glorious-codes / glorious-pitsby

Docs generator for AngularJS, Vue, React, and Vanilla components.
https://pitsby.compilorama.com
MIT License
90 stars 7 forks source link

Serving pitsby through http-server throws console error and does not show on browser #160

Closed aoloo closed 4 years ago

aoloo commented 4 years ago

Current Issue: image

Implementation: index.html

<body ng-app="pitsby-app">
    <ui-view></ui-view>
    <script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.7.9/angular.js"></script>
    <script crossorigin src="https://unpkg.com/react@16.13.0/umd/react.development.js"></script>
    <script crossorigin src="https://unpkg.com/react-dom@16.13.0/umd/react-dom.development.js"></script>
    <script type="text/javascript" src="main.js"></script>
</body>

pitbsy.config.js

module.exports = {
  outputDirectory: './documentation',
  projects: [
    {
      engine: 'react',
      collectDocsFrom: './src/',
    },
  ],
};

Not sure what is causing the issue because I am following these steps `

rafaelcamargo commented 4 years ago

Well, there are a couple of things that seems to be causing your problem:

a) Do you have any .doc.js file in your src directory? You need at least one .doc.js. This file is an object that represents the documentation for some of your components. Take a look at how I wrote a .doc.js file for the Button present on Pitsby Live Demo. b) In your config file, you need to specify where Pitsby can find the assets for your library. Since your file seems to configure a React project, you should make sure that your library exports your components as UMD (Universal Module Definition)

Solving these two issues, the directory ./documentation will likely be created properly 👍

If you'd like to see some real example of configuration, check out the Pitsby Live Demo's Repo.

For any other question, don't hesitate to contact me again. It's a pleasure to help 🙂

aoloo commented 4 years ago

Thank you rafael for your response. We have some of the components dir with .doc.js. Does this mean in order for pitsby to work we would need all our components dir being copied from the /src directory have a file with a .doc.js extension in the specific component dir? Also for step two would we have both pitsby.config.js and pitsby.conf.dev.js to link to the path of our components dir in the src? In our case it would ./src/components/. I really appreciate the quick support turn around.

rafaelcamargo commented 4 years ago

We have some of the components with .doc.js. Does this mean in order for pitsby to work we would need all our components being copied from the /src directory have a .doc.js extension?

You need to have one .doc.js file per component. This file is not your component file. It's your component documentation file. On the section The Documentation File of this page, you can see how the object should be exported.

This is not complicated. For example, if I have a library that offers a component Button, I'll have a component file called button.js (this file belongs to my library) and a component documentation file called button.doc.js. Considering a library that exports React components, see below:

// button.js
import React from 'react';

export const Button = ({ onClick, children }) => {
  return (
    <button onClick={ onClick }>{ children }</button>
  );
};
// button.doc.js
module.exports = {
  name: 'Button',
  description: 'Abstraction of a native button.',
  properties: [
    {
      name: 'on-click',
      type: '<void> Function',
      values: 'any'
    }
  ],
  // The following list of object will become the examples that you'll see
  // on your documentation site the same way you see on Pitsby Live Demo website.
  // You can create as many examples as you want.
  examples: [
    {
      title: 'Default Button',
      controller: function() {
        const { Button } = reactComponents;
        // reactComponents is the name you gave to your
        // React library when bundling it as UMD.

        return function(){
          const onClick = () => {
            window.alert("Clicked!");
          };
          return (
            <Button onClick={ onClick }>
              Click Here
            </Button>
          );
        }
      }
    }
  ]
};

Also for step two would we both pitsby.config.js and pitsby.conf.dev.js to link to the path of our components dir in the src?

On Pitsby Live Demo repository you saw a pitsby.conf.dev.js and a pitsby.conf.prod.js because the name of the assets changes depending on environment. In production, the file is named as library.min.js and in development it's just library.js. But if you don't need to handle this things, there's no problem in having just one config file (pitsby.config.js).

What you have to make sure is that you are listing all the script and style files that your library generates. Example:

module.exports = {
  projects: [
    {
      engine: 'react',
      collectDocsFrom: './src/components' // Pitsby will look for ".doc.js" files inside this directory.
    }
  ],
  styles: [
    './dist/reactComponents.css'
    // This is the file containing all the styles my library exports.
  ],
  scripts: [
    './dist/reactComponents.js'
    // This is the file containing all the scripts my library exports.
  ]
};

Doing this, reactComponents.css and reactComponents.js will be included on the documentation website generated by Pitsby.

Important: Pitsby doesn't transpile files so you need build your library (using webpack, rollup, broccoli, whatever) and list the generated assets (scripts/styles) on the configuration file. If you list source files on the configuration file, it won't work.

That's it 👍