Add docs and improve developer experience.

README.md

@@ -69,4 +69,6 @@ outline init
 
 Detailed information regarding how to contribute to Outline development, can be found in [CONTRIBUTING.md](./CONTRIBUTING.md). **Expect this information to be refined soon.**
 
+Please see [./docs/README.md](./docs/README.md) for information about developing for Outline.
+
 [![Deploys by Netlify](https://www.netlify.com/v3/img/components/netlify-color-accent.svg 'Deploys by Netlify')](https://www.netlify.com)

docs/README.md

@@ -1 +1,32 @@
 # Outline Documentation
+
+Developing for Outline has different considerations than developing with Outline.
+
+## Developing With Outline
+
+If you are using Outline to create a design system, you should refer to the scaffolding information in the main [../README.md](README.md) file along with the documentation in the [../packages/outline-docs](@phase2/outline-docs) package. This package should be added by default when you initialize your Outline project and its contents should show in your project's Storybook instance.
+
+## Developing For Outline
+
+If you are developing to improve Outline there are two modes to consider for Outline packages:
+
+ * running in the context of the Outline project
+ * running in the context of a project using Outline.
+
+Running in the context of the Outline project is relatively straightforward as it simply involves running commands in this repo. For example, `yarn run start` will start Storybook in dev mode. Running in the context of a project, however, is more complicated. There are two techniques you should be aware of.
+
+### Linking
+
+If you want to test your work within the context of a project and your change doesn't involve the installation of a package or initialization of a project, [linking techniques](https://classic.yarnpkg.com/lang/en/docs/cli/link/) may be sufficient for your needs.
+
+### Outline CLI and project template development
+
+When adjusting the project initialization process it can be executed via direct reference instead of using the `@phase2/outline-cli` package. There is also a flag to the `init` command, `-l`, that will cause the templates used to come from the `../packages/outline-templates` and `../packages/outline-storybook` directories instead of the published `@phase2/outline-templates` and `@phase2/outline-storybook` packages. It will also cause the initial `yarnpkg` command in the generated project to be skipped.
+
+For example, to spin up a project directory as a sibling to this repo run:
+
+```bash
+npx ./outline/packages/outline-cli init -l
+```
+
+> Note: Do not forget to execute a build before testing the project initialization process. Use of the -l flag does not currently cause any initially installed packages to use linking technique above.

packages/outline-cli/src/actions/init/init-project.ts

@@ -12,35 +12,40 @@ export type Prompts = {
   description: string | null;
 };
 /**
- * @param {string} prompts - prompts: Object of the values from the prompt questions;
+ * @param {string} prompts - Object of the values from the prompt questions;
+ * @param {boolean} [local=false] - Whether to run in local development mode;
  * @returns {void}
  */
-export const initProject = (prompts: Prompts): void => {
+export const initProject = (prompts: Prompts, local: boolean = false): void => {
   const currDir = process.cwd();
   const resolvedPath = path.resolve(currDir, prompts.slug);
-  const storybookSource = path.resolve(
-    resolvedPath,
-    './node_modules/@phase2/outline-storybook'
-  );
-  const starterPath = path.resolve(
-    `${resolvedPath + '/node_modules/@phase2/outline-templates/'}`,
-    prompts.template
-  );
+  const storybookSource = local
+    ? `${__dirname}/../../../../outline-storybook`
+    : path.resolve(resolvedPath, './node_modules/@phase2/outline-storybook');
+  const starterPath = local
+    ? `${__dirname}/../../../../outline-templates/${prompts.template}`
+    : path.resolve(
+        `${resolvedPath + '/node_modules/@phase2/outline-templates/'}`,
+        prompts.template
+      );
 
   mkdirsSync(resolvedPath);
   process.chdir(resolvedPath);
   console.log(`${chalk.blue('info')}: Moved to directory: ${resolvedPath}`);
-  console.log(
-    `${chalk.bold.blue('info')}: Downloading Outline ${
-      prompts.template
-    } starter template`
-  );
-  execSync(
-    `yarn add @phase2/outline-templates @phase2/outline-storybook --cwd='./'`,
-    {
-      stdio: [0, 1, 2],
-    }
-  );
+
+  if (!local) {
+    console.log(
+      `${chalk.bold.blue('info')}: Downloading Outline ${
+        prompts.template
+      } starter template`
+    );
+    execSync(
+      `yarn add @phase2/outline-templates @phase2/outline-storybook --cwd='./'`,
+      {
+        stdio: [0, 1, 2],
+      }
+    );
+  }
 
   // Move the default files to the root directory.
   try {
@@ -58,8 +63,10 @@ export const initProject = (prompts: Prompts): void => {
     throw console.error(`${chalk.red('error')}: ${error}`);
   }
 
-  console.log(`${chalk.blue('info')}: Installing Outline dependencies`);
-  execSync('yarnpkg', { stdio: [0, 1, 2] });
+  if (!local) {
+    console.log(`${chalk.blue('info')}: Installing Outline dependencies`);
+    execSync('yarnpkg', { stdio: [0, 1, 2] });
+  }
 
   // NPM does not package .gitignore files. To include it we renamed it. Now rename it correctly.
   try {

packages/outline-cli/src/commands/init.ts

@@ -23,6 +23,11 @@ export default class Init extends Command {
       char: 'd',
       description: 'Project description.',
     }),
+    local: Flags.boolean({
+      char: 'l',
+      description: 'Run in local development mode.',
+      default: false,
+    }),
     template: Flags.string({ char: 't', description: 'Project template.' }),
   };
 
@@ -111,7 +116,7 @@ export default class Init extends Command {
         description: description.description,
         template: template.template,
       };
-      initProject(prompts);
+      initProject(prompts, flags.local);
     } else {
       // Enable "manual mode".
       const prompts: Prompts = {
@@ -121,7 +126,7 @@ export default class Init extends Command {
         description: flags.description ?? 'Design system built with OutlineJS.',
         template: flags.template ?? 'default',
       };
-      initProject(prompts);
+      initProject(prompts, flags.local);
     }
   }
 }