Merge pull request #1154 from nxext/improve-docs

docs(capacitor,ionic-angular): standardize and improve plugin docs

docs/.vitepress/config.mts

@@ -110,8 +110,8 @@ function sideNavDocs() {
       collapsed: true,
       items: [
         {
-          text: 'Installation',
-          link: '/docs/ionic-angular/installation',
+          text: 'Overview',
+          link: '/docs/ionic-angular/overview',
         },
         {
           text: 'Generators',

docs/docs/capacitor/overview.md

@@ -1,92 +1,78 @@
-The `@nxext/capacitor` plugin lets you interact with the Capacitor CLI using Nx targets.
+## `@nxext/capacitor` Plugin
 
-## Install Plugin
+### Overview
 
-```
-# npm
-npm install --save-dev --exact @nxext/capacitor
-
-# yarn
-yarn add --save-dev --exact @nxext/capacitor
-```
+The `@nxext/capacitor` plugin provides Nx targets to interact with the Capacitor CLI.
 
-## Add Capacitor to Existing Project
+### Installation
 
-First, ensure that the frontend project has been built:
-
-```
-nx build {frontend project name}
+Install the plugin in your Nx workspace:
 
-nx build mobile-app
+```bash
+npm install --save-dev @nxext/capacitor
 ```
 
-Once the plugin has been added to your Nx workspace you can generate a Capacitor project from an existing frontend project:
+#### Configure Capacitor
 
+```bash
+nx generate @nxext/capacitor:configuration --project=my-app
 ```
-nx generate @nxext/capacitor:configuration --project {frontend project name}
 
-nx generate @nxext/capacitor:configuration --project mobile-app
-```
-
-Nx will ask you some questions about the application, but you can customize it further by passing these options:
+:::info  
+This plugin configures an existing application.
+If you don't have an application yet, visit the [Nx documentation](https://nx.dev/getting-started/intro#pick-your-stack) to generate one.  
+:::
 
-```
-nx generate @nxext/capacitor:configuration [options,...]
-
-Options:
-  --project               The name of the frontend project for Capacitor.
-  --appId                 The app ID for the project. (default: io.ionic.starter)
-  --appName               The application name for the project.
-  --webDir                The directory of your projects built web assets.
-  --skipFormat            Skip formatting files.
-  --dryRun                Runs through and reports activity without writing to disk.
-  --skip-nx-cache         Skip the use of Nx cache.
-  --help                  Show available options for project target.
-```
+### Usage
 
-Finally, you will need to `cd` into your applications directory and install the npm dependencies. (e.g. `npm install`)
+#### Add Native Platforms
 
-## Add Native Platforms
-
-Now that a Capacitor project has been added to your Nx workspace you can begin adding support for native platforms. Currently, Capacitor supports Android and iOS, but other platforms can be added with Capacitor plugins.
-
-```
-nx run {frontend project}:add:ios
-nx run {frontend project}:add:android
-nx run {frontend project}:add --platform {native platform}
+Add support for native platforms like Android and iOS:
 
+```bash
 nx run my-app:add:android
-nx run my-app:cap --cmd="add android"
+nx run my-app:add:ios
 ```
 
-## Sync Native Platform
-
-Running the sync command will update the native platform dependencies and copy a build of your frontend project to the Capacitor project:
+#### Sync Native Platforms
 
-```
-nx run {frontend project}:sync:ios
-nx run {frontend project}:sync:android
-nx run {frontend project}:sync --platform {native platform}
+Sync the native platforms to update dependencies and copy the built frontend:
 
+```bash
 nx run my-app:sync:android
-nx run my-app:cap --cmd="sync android"
+nx run my-app:sync:ios
 ```
 
-## Open Native Platform
+**For iOS Podfile Initialization:**
 
-Finally, you can open the native platform in it's respective IDE:
+1. Navigate to the `ios/App` folder:
+   ```bash
+   cd apps/my-app/ios/App
+   ```
+2. Run `pod install`.
 
-```
-nx run {frontend project}:open:ios
-nx run {frontend project}:open:android
-nx run {frontend project}:open --platform {native platform}
+#### Open Native Platforms
 
+Open the native project in the respective IDE:
+
+```bash
 nx run my-app:open:android
-nx run my-app:cap --cmd="open android"
+nx run my-app:open:ios
 ```
 
-## Adding Capacitor Plugins
+### Notes on Capacitor Plugins
 
 Capacitor plugin dependencies must be added to the project-level `package.json`.
 
-To learn more about Capacitor, including the native API's available, please read the [official Capacitor documentation](https://capacitorjs.com/docs).
+```jsonc
+// ./apps/my-app/package.json
+{
+  "name": "my-app",
+  "dependencies": {
+    "@capacitor/android": "../../node_modules/@capacitor/android",
+    "@capacitor/ios": "../../node_modules/@capacitor/ios",
+    // Example plugin
+    "@capacitor-community/apple-sign-in": "../../node_modules/@capacitor-community/apple-sign-in"
+  }
+}
+```

docs/docs/ionic-angular/overview.md

@@ -0,0 +1,84 @@
+## `@nxext/ionic-angular` Plugin
+
+### Overview
+
+The `@nxext/ionic-angular` plugin configures Ionic and Capacitor for an Angular application in your Nx workspace.
+
+### Installation
+
+Install the plugin in your Nx workspace:
+
+```bash
+npm install @nxext/ionic-angular --save-dev
+```
+
+### Usage
+
+1. **Generate a New Angular Project (Optional):**
+
+   ```bash
+   nx g @nx/angular:application --directory=apps/my-app
+   ```
+
+2. **Add Ionic and Capacitor Configuration:**
+
+   ```bash
+   nx g @nxext/ionic-angular:configuration my-app
+   ```
+
+:::info  
+This plugin configures an existing Angular application.
+If you don't have an application yet, visit the [Nx documentation](https://nx.dev/nx-api/angular) to generate one.  
+:::
+
+### Notes on Capacitor Plugins
+
+Capacitor plugin dependencies must be added to the project-level `package.json`.
+
+```jsonc
+// ./apps/my-app/package.json
+{
+  "name": "my-app",
+  "dependencies": {
+    "@capacitor/android": "../../node_modules/@capacitor/android",
+    "@capacitor/ios": "../../node_modules/@capacitor/ios",
+    // Example plugin
+    "@capacitor-community/apple-sign-in": "../../node_modules/@capacitor-community/apple-sign-in"
+  }
+}
+```
+
+#### Add Native Platforms
+
+Add support for Android and iOS platforms:
+
+```bash
+nx run my-app:add:ios
+nx run my-app:add:android
+```
+
+#### Sync Native Platforms
+
+Update native platform dependencies and copy the built frontend to the Capacitor project:
+
+```bash
+nx run my-app:sync:ios
+nx run my-app:sync:android
+```
+
+**For iOS Podfile Initialization:**
+
+1. Navigate to the `ios/App` folder:
+   ```bash
+   cd apps/my-app/ios/App
+   ```
+2. Run `pod install`.
+
+#### Open Native Platforms
+
+Open the native project in the respective IDE:
+
+```bash
+nx run my-app:open:ios
+nx run my-app:open:android
+```

docs/index.md

@@ -33,8 +33,8 @@ features:
     link: /docs/preact/overview.html
   - title: Ionic
     details: A new way to build and ship for mobile.
-    link: /docs/ionic-angular/installation.html
+    link: /docs/ionic-angular/overview.html
   - title: Capacitor
     details: A cross-platform native runtime for web apps.
-    link: /docs/capacitor/generators.html
+    link: /docs/capacitor/overview.html
 ---