setup docs site

.gitignore

@@ -2,4 +2,3 @@ node_modules/
 .pnpm-debug.log
 
 test/
-docs/

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Arun George
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

NOTES.md

@@ -0,0 +1,43 @@
+# Notes
+
+## Additional Reading
+
+- [git sparse-checkout](https://github.blog/2020-01-17-bring-your-monorepo-down-to-size-with-sparse-checkout/)
+- [git submodules](https://www.atlassian.com/git/tutorials/git-submodule)
+- [git subtree](https://www.atlassian.com/git/tutorials/git-subtree)
+- [pnpm](https://pnpm.io/pnpm-cli)
+- [lage](https://microsoft.github.io/lage/)
+- [turborepo](https://turborepo.org/docs)
+
+## sparse-checkouts
+
+```sh
+git clone --filter=blob:none --no-checkout {repo}
+cd {repo}
+git checkout {branchName}
+git sparse-checkout init --cone
+git sparse-checkout set [...allSubDirs]
+```
+
+## pnpm
+
+### [link-workspace-packages](https://pnpm.io/workspaces#link-workspace-packages)
+
+- "If you need local packages to also be linked to subdependencies, you can use the `deep` setting"
+
+  ```json
+  "pnpm": {
+      "link-workspace-packages": "deep"
+  }
+  ```
+
+### [prefer-workspace-packages](https://pnpm.io/workspaces#prefer-workspace-packages)
+
+- pros: don't have to explicitly list all packages in the `pnpm.overrides` section.
+- cons: if you're linking a repo with HEAD pointing to pre-release packages, those won't be used/linked due to semver 😕
+
+  ```json
+  "pnpm": {
+      "prefer-workspace-packages": true
+  }
+  ```

README.md

@@ -10,60 +10,26 @@ Setup a `CoSpace` to link multiple (mono)repos together!
 
 ## Getting started
 
-1. Install `cospace`, then run `npx cospace init`
+### Initialize
 
-1. Clone all the repos you want to link together under the `repos` directory. You can use [sparse checkouts](https://github.blog/2020-01-17-bring-your-monorepo-down-to-size-with-sparse-checkout/) to only clone the directories you need.
-
-1. Update the [pnpm-workspace.yaml](pnpm-workspace.yaml) file with all the packages you want to add to your CoSpace.
-
-1. Update the [cospace.code-workspace](cospace.code-workspace) file with all the repos you want to add to your VsCode multi root workspace.
-
-1. (Optional) Run `pnpm setOverrides` to automatically update the `pnpm.overrides` section of the CoSpace's [package.json](package.json), to use the local package version from the workspace, disregarding semver. Useful for when you have pre-release versions of packages in your workspace.
-
-1. Run `pnpm install` to install all the packages you've added to your CoSpace.
-
-1. Run `pnpm build` to build all the packages you've added to your CoSpace using your monorepo task runner. I'm using [lage](https://microsoft.github.io/lage/), but [turborepo](https://turborepo.org/docs) should theoretically work.
-
-## Notes
-
-### Additional Reading
-
-- [git sparse-checkout](https://github.blog/2020-01-17-bring-your-monorepo-down-to-size-with-sparse-checkout/)
-- [git submodules](https://www.atlassian.com/git/tutorials/git-submodule)
-- [git subtree](https://www.atlassian.com/git/tutorials/git-subtree)
-- [pnpm](https://pnpm.io/pnpm-cli)
-- [lage](https://microsoft.github.io/lage/)
-- [turborepo](https://turborepo.org/docs)
+```bash
+npx cospace@latest init my-cospace
+```
 
-### sparse-checkouts
+### Link your (mono)repos
 
-```sh
-git clone --filter=blob:none --no-checkout {repo}
-cd {repo}
-git checkout {branchName}
-git sparse-checkout init --cone
-git sparse-checkout set [...allSubDirs]
+```bash
+cd my-cospace
 ```
 
-### pnpm
+1. Clone all the repos you want to link together under the `repos` sub directory.
 
-#### [link-workspace-packages](https://pnpm.io/workspaces#link-workspace-packages)
+1. Update the `pnpm-workspace.yaml` file with all the packages you want to add to your CoSpace. By default all packages under the `repos` directory will be added to your CoSpace, but you probably want to add them at a more granular level.
 
-- "If you need local packages to also be linked to subdependencies, you can use the `deep` setting"
+1. Update the `cospace.code-workspace` file with all the repos you want to add to your [vscode multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces).
 
-  ```json
-  "pnpm": {
-      "link-workspace-packages": "deep"
-  }
-  ```
+1. Run `pnpm exec cospace override` to link all the packages in your CoSpace together.
 
-#### [prefer-workspace-packages](https://pnpm.io/workspaces#prefer-workspace-packages)
+1. Run `pnpm install` to install all the packages you've added to your CoSpace.
 
-- pros: don't have to explicitly list all packages in the `pnpm.overrides` section.
-- cons: if you're linking a repo with HEAD pointing to pre-release packages, those won't be used/linked due to semver 😕
-
-  ```json
-  "pnpm": {
-      "prefer-workspace-packages": true
-  }
-  ```
+1. Run `pnpm build` to build all the packages you've added to your CoSpace using your monorepo task runner. By default we use [lage](https://microsoft.github.io/lage/), but [turborepo](https://turborepo.org/docs) should theoretically work.

cli/README.md

@@ -4,10 +4,11 @@ Setup a `CoSpace` to link multiple (mono)repos together!
 
 ## Getting Started
 
-### Pre-requisites
+## Prerequisites
 
 - [pnpm](https://pnpm.io/installation)
   - If you're using [Node.js](https://nodejs.org/en/download/) version ^14.19 or ^16.9 you just need to enable pnpm via [corepack](https://github.com/nodejs/corepack).
+  - Otherwise install via `npm i -g pnpm`
 
 ### Create a new `CoSpace`
 
@@ -25,28 +26,31 @@ cd my-cospace
 
 1. Clone all the repos you want to link together under the `repos` sub directory.
 
-1. Update the `pnpm-workspace.yaml` file with all the packages you want to add to your `CoSpace`. By default all packages under the `repos` directory will be added to your `CoSpace`, but you probably want to be more specific.
+1. Update the `pnpm-workspace.yaml` file with all the packages you want to add to your CoSpace. By default all packages under the `repos` directory will be added to your CoSpace, but you probably want to add them at a more granular level.
 
 1. Update the `cospace.code-workspace` file with all the repos you want to add to your [vscode multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces).
 
-1. Run `pnpm install` to install all the packages you've added to your `CoSpace`.
+1. Run `pnpm exec cospace override` to link all the packages in your CoSpace together.
 
-1. Run `pnpm build` to build all the packages you've added to your `CoSpace` using your monorepo task runner. By default we use [lage](https://microsoft.github.io/lage/), but [turborepo](https://turborepo.org/docs) should work as well.
+1. Run `pnpm install` to install all the packages you've added to your CoSpace.
+
+1. Run `pnpm build` to build all the packages you've added to your CoSpace using your monorepo task runner. By default we use [lage](https://microsoft.github.io/lage/), but [turborepo](https://turborepo.org/docs) should theoretically work.
 
 ## Advanced Usage
 
-### override
+### `override`
 
 ```bash
 npx cospace@latest override
 ```
 
-- Automatically update the `pnpm.overrides` section of the `CoSpace`'s `package.json`, to ignore [semver](https://semver.org/) and always use the local package version from the workspace. Useful for when you have pre-release versions of packages in your workspace.
+- Automatically update the `pnpm.overrides` section of the CoSpace's `package.json`, to ignore semver and always use the local package version (`"workspace:*"`) from the workspace. Useful for when you have pre-release or different major versions of packages in your workspace.
 
-### purge
+### `purge`
 
 ```bash
 npx cospace@latest purge
 ```
 
-- Recursievely delete all `node_modules` from the `CoSpace`.
+- Recursievely delete all `node_modules` from the CoSpace.
+

cli/package.json

@@ -3,10 +3,11 @@
   "version": "0.4.3",
   "description": "Setup a `CoSpace` to link multiple (mono)repos together!",
   "author": "https://github.com/aruniverse",
+  "homepage": "https://aruniverse.github.io/cospace",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/aruniverse/cospace/tree/master/cospace/cli"
+    "url": "https://github.com/aruniverse/cospace.git"
   },
   "type": "module",
   "bin": {

docs/.env

@@ -0,0 +1 @@
+USE_SSH=true

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/blog/authors.yml

@@ -0,0 +1,5 @@
+arun:
+  name: Arun George
+  title: Maintainer of CoSpace
+  url: https://github.com/aruniverse
+  image_url: https://github.com/aruniverse.png

docs/docs/ack.md

@@ -0,0 +1,19 @@
+---
+sidebar_position: 5
+---
+
+# Acknowledgements
+
+## Powered by
+
+- [vscode multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces)
+- [pnpm workspaces](https://pnpm.io/workspaces)
+- [lage](https://microsoft.github.io/lage/)
+
+## Special thanks to
+
+- [@calebmshafer](https://github.com/calebmshafer)
+  - Inspired and helped design the first initial prototype which used [Rush](https://rushjs.io/) to manage the linking of packages.
+
+- [@medokin](https://github.com/medokin)
+  - For transferring the [cospace](https://www.npmjs.com/package/cospace) package name ownership over.

docs/docs/cli-usage.md

@@ -0,0 +1,35 @@
+---
+sidebar_position: 3
+---
+
+# CLI Usage
+
+```bash
+npx cospace@latest <command> [<args>] 
+```
+
+## Commands
+
+### `init`
+
+```bash
+npx cospace@latest init <dir>
+```
+
+- Initialize a new CoSpace under the directory specified with all the config files needed. If `<dir>` is not provided, will default to current directory.
+
+### `override`
+
+```bash
+npx cospace@latest override
+```
+
+- Automatically update the `pnpm.overrides` section of the CoSpace's `package.json`, to ignore semver and always use the local package version (`"workspace:*"`) from the workspace. Useful for when you have pre-release or different major versions of packages in your workspace.
+
+### `purge`
+
+```bash
+npx cospace@latest purge
+```
+
+- Recursievely delete all `node_modules` from the CoSpace.

docs/docs/faq.mdx

@@ -0,0 +1,18 @@
+---
+title: "Frequently Asked Questions"
+sidebar_label: "FAQ"
+sidebar_position: 4
+---
+
+## What are the Pros & Cons?
+
+### Pros
+
+- Easily link multiple (mono)repos together that use different package managers.
+- Don't have to manually link packages yourself with `npm link` or `yarn link` or `pnpm link`.
+- Ignore [semver](https://semver.org/) versioning, especially useful when working with pre-release versions.
+- Verify your dependencies are set up correctly.
+
+### Cons
+
+- If a package's dependencies are updated, the lockfile its apart of will not be updated, and you'll have to do that yourself outside the CoSpace unless you purge and re-install.