first draft docs for 1.0a2

docs/cli.md

@@ -0,0 +1,102 @@
+## Publisher CLI
+
+### `list-accounts`
+
+This command pulls from both the `IDE` and `rsconnect-python` saved servers
+list.
+
+```
+publisher list-accounts
+```
+
+### `init`
+
+```
+publisher init ${DIRECTORY}
+```
+
+The `init` command inspects the files in the specified project directory, or the
+current directory if omitted. It creates an initial configuration file for you
+in `.posit/publish/default.toml`. In the future we will support multiple
+configuration files. For now, only `default`.
+
+The client auto-detects the type of content in `DIRECTORY`.
+
+For Python apps, `publisher` looks for a single Python source file in the
+directory to be the entrypoint. If there are multiple python files, one of them
+must be named `app.py`, `api.py`, `main.py`, or  `streamlit_app.py`.
+
+For Quarto projects, `publisher` looks for a .qmd file with the same name as the
+project directory, or for a single .qmd file to be the entrypoint.
+
+Note: If the content type or entrypoint cannot be detected, the publisher sends
+an error instructing you to manually update the default.toml file created.
+
+Initialization also records the Python version and packages in use. You can
+specify which Python interpreter to query with the `--python` option. You can
+also provide a package list in `requirements.txt`. If you don't, one will be
+created for you with `python -m pip freeze`; however, this is not recommended.
+
+Currently, the UI/VSCode extension automatically runs `init` if there is no
+configuration file. You can run `init` again if you need to, but note that it
+will overwrite the default configuration file.
+
+### `deploy`
+
+The sample command below allows you to deploy a new content item in the Connect
+account specified. Replace the `${ACCOUNT}` placeholder with a nickname of a
+Connect account from the `list-accounts` command above.
+
+Minimal sample command:
+
+```
+publisher deploy --name ${NAME} --account ${ACCOUNT} ${DIRECTORY}
+```
+
+or
+
+```
+publisher deploy -n ${NAME} --a ${ACCOUNT} ${DIRECTORY}
+```
+
+Creating a deployment publishes the contents of `DIRECTORY` to Connect, and
+creates a record of the deployment in `.posit/publish/deployments/${NAME}.toml`
+([schema](https://cdn.posit.co/publisher/schemas/posit-publishing-record-schema-v3.json)).
+`DIRECTORY` is optional, and defaults to the current directory.
+
+
+It is OK to rename deployment files as long as they live in
+`.posit/publish/deployments` and have a `.toml` suffix. Deleting a deployment
+file is also OK, and will cause `publisher` to forget about that deployment.
+Neither action will cause a change to anything in Connect.
+
+### `redeploy`
+
+The sample command below allows you to redeploy a pre-existing, named
+deployment.
+
+```
+publisher redeploy ${NAME} ${DIRECTORY}
+```
+
+`NAME` is the deployment name you provided in the `deploy` command.
+
+`DIRECTORY` is optional, and defaults to the current directory.
+
+## `publisher ui`
+
+To launch the Posit Publisher UI in a browser, run the following command:
+```
+publisher ui ${DIRECTORY}
+```
+This returns an address you can visit or, if you include the `-i` flag, launches
+an interactive browser session.
+
+## help
+
+Each `publisher` CLI command supports a `-h` option, which will show the help
+for that command.
+
+```
+publisher ui -h
+```

docs/index.md

@@ -0,0 +1,63 @@
+# Posit Publisher
+
+Posit Publisher lets you publish projects to Connect. This version only supports
+Python projects, and Quarto projects using Python. Support for R projects is
+planned for a later release.
+
+Key concepts:
+* Publisher provides a binary with a CLI and a UI server. There is also a VSCode
+  extension that runs the binary and hosts the UI in VSCode.
+* Deployment options are set via a configuration file in `.posit/publish/`.
+* Records of where you have deployed are kept in `.posit/publish/deployments`.
+* Accounts/credentials are currently read from rsconnect and rsconnect-python.
+
+
+## Features
+
+Supported features:
+
+* Publish projects to Connect
+* UI available via VSCode extension
+* Publish using CLI, or launch the UI for browser access
+* Configuration-file based workflow
+* Configuration schema enables editing with the [Even Better TOML
+  VSCode](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)
+  extension
+* Exclude files from deployment with `.positignore` files (like `.gitignore`)
+* Python content: APIs, applications, and notebooks
+* Automatic detection of client Python and Quarto version
+* Automatic creation of a requirements.txt file (using `pip freeze`) if needed
+* Publish Quarto documents (using the `jupyter` and `markdown` engines only)
+* Collaborate via git, or by downloading a source bundle from Connect
+* Uses existing publishing accounts from `rsconnect` and `rsconnect-python`
+* Pre-flight checking of settings before deploying to Connect
+* Verification that deployed apps can successfully start
+
+What's not supported yet but is on our to-do list:
+
+* Publish to servers other than Connect (shinyapps.io, Cloud, etc)
+* Manage the list of accounts and provide an import function for existing
+  accounts
+* R content such as Shiny, R Markdown, and Quarto (with the `knitr` engine)
+* Automatic detection of R version and dependencies
+* Support for multiple configuration files and configuration editing in the UI
+* Show more information in the UI such as package dependencies
+* Inject secrets as environment variables
+* More metadata such as tags, thumbnail image, etc
+* Configure permissions for sharing
+* Option to export a `manifest.json` for compatibility with prior tool
+* Schedule reports
+* Streamlined `update deployment` command in VSCode extension
+* Support VSCode windows with multiple workspaces, or publish from a
+  subdirectory of the workspace
+* Better error handling
+
+
+## Installation
+See the [Installation](installation.md) page.
+
+## Getting Started
+There are three ways to publish content.
+* [publisher cli](cli.md)
+* [publisher ui](ui.md)
+* [Publish Assistant in Positron + VSCode](vscode.md)

docs/installation.md

@@ -0,0 +1,172 @@
+This page walks you through installation options for Posit Publisher.
+
+## Installation for VSCode / Positron
+The VSCode extension package includes everything you need to get started within
+VSCode or Positron.
+
+Download and install the VSCode extension.
+[https://cdn.posit.co/publisher/releases/tags/v1.0.alpha1/publisher-1.0.alpha1.vsix](https://cdn.posit.co/publisher/releases/tags/v1.0.alpha1/publisher-1.0.alpha1.vsix).
+
+To learn how to install a `.vsix` file, see the [Install from a
+VSIX](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-from-a-vsix)
+guide from Visual Studio Code.
+
+## Optional: Install the CLI
+
+If you want to try deploying from the command line, or use the UI in a browser,
+install the `publisher` CLI.
+
+### Script installation
+
+**This method is available for macOS and Linux only.**
+
+Follow the [manual installation](#manual-installation) instructions below for
+other operating systems.
+
+Paste the following command into your terminal or shell prompt.
+
+The script explains what it does and then pauses before it does it.
+
+```console
+/bin/bash -c "$(curl -fsSL https://cdn.posit.co/publisher/install.bash)"
+```
+
+### Manual installation
+
+1. Go to [GitHub
+   releases](https://github.com/rstudio/publishing-client/releases).
+1. Select the Posit Publisher version for installation.
+1. Download the asset for your operating system and architecture. See below for
+   additional information on operating systems and architectures.
+1. Once downloaded, extract the archive file (e.g., unzip or untar).
+1. Install the executable in a location available on your `PATH` (e.g.,
+   `/usr/local/bin`).
+    1. To view locations on your PATH, invoke `/bin/bash -c "echo $PATH"` from
+       your terminal or shell prompt.
+    1. In most cases, the correct installation location is `/usr/local/bin` on
+       macOS and Linux operating systems.
+    1. Use the following command to install and set the correct permissions on
+       Linux or macOS:
+    1. `sudo install -o root -g wheel -m 0755 ./bin/publisher /usr/local/bin`.
+       Replace `/usr/local/bin` with your preferred installation directory.
+       Otherwise, you may need to allow access manually after first invocation.
+
+## Verification
+
+### MacOS
+
+Verify that you have installed Posit Publisher.
+
+1. In MacOS, open Spotlight.
+1. In the search box, type `Terminal`, then press Return.
+1. In the Terminal window that appears, type the following command:
+
+```console
+publisher
+```
+
+#### Permissions
+
+If prompted with the following, click **Ok**, then go to **Settings** ->
+**Privacy & Security** and click **Always Allow**.
+
+> “publisher” can’t be opened because Apple cannot check it for malicious
+> software.
+
+### Windows
+
+Verify that you have installed Posit Publisher.
+
+1. In Windows, click the Start menu.
+1. In the search box, type `cmd`, then press Enter.
+1. In the Command Prompt window that appears, type the following command:
+
+```console
+publisher
+```
+
+### Linux
+
+Verify that you have installed Posit Publisher.
+
+1. Open a shell prompt and type the following command.
+
+```console
+publisher
+```
+
+## Operating systems
+
+The following operating systems are supported.
+
+### macOS
+- macOS 12 (Monterey)
+- macOS 13 (Ventura)
+- macOS 14 (Sonoma)
+
+#### Architectures
+
+##### Apple Silicon (M-Series) / ARMv8.5-A / ARMv8.6-A
+
+When running MacOS with Apple silicon processors, install `darwin-arm64.tar.gz`.
+
+This includes, but is not limited to, the following processors:
+
+- Apple M1
+- Apple M1 Pro
+- Apple M1 Max
+- Apple M1 Ultra
+- Apple M2
+- Apple M2 Pro
+- Apple M2 Max
+- Apple M2 Ultra
+- Apple M3
+- Apple M3 Pro
+- Apple M3 Max
+
+##### x86-64 / x86_64 / x64 / AMD64 / Intel 64
+
+When running MacOS with x86-64 compliant processors, install
+`darwin-amd64.tar.gz`.
+
+This includes all Apple Mac products before Apple Silicon.
+
+### Windows
+
+- Windows 10
+- Windows 11
+
+#### Architectures
+
+##### x86-64 / x86_64 / x64 / AMD64 / Intel 64
+
+When running Windows with x86-64 compliant processors, install
+`windows-amd64.tar.gz`.
+
+### Linux
+
+- RHEL 8
+- RHEL 9
+- Ubuntu 20.04 (focal)
+- Ubuntu 22.04 (jammy)
+- SUSE Linux Enterprise Server 15 SP5
+- openSUSE 15.5
+
+#### Architectures
+
+##### ARM64 / AArch64 / ARMv8 / ARMv9
+
+When running Linux with ARM64 compliant processors, install
+`linux-arm64.tar.gz`.
+
+##### x86-64 / x86_64 / x64 / AMD64 / Intel 64
+
+When running Linux with x86-64 compliant processors, install
+`linux-amd64.tar.gz`.
+
+### Support grid
+
+|             | `darwin` | `linux` | `windows` |             |
+| ----------: | :------: | :-----: | :-------: | :---------- |
+| **`amd64`** |   `x`    |   `x`   |    `x`    | **`amd64`** |
+| **`arm64`** |   `x`    |   `x`   |           | **`arm64`** |

docs/ui.md

@@ -0,0 +1,52 @@
+When you open the Posit Publisher UI from VSCode/Positron or the command line,
+you first land on the the **Project** page. This page shows the deployments you
+have made from this project directory, along with the configuration files, and a
+list of your project files.
+
+<p><img width="400px" src="https://cdn.posit.co/publisher/docs/images/ui-project.png"/></p>
+
+Notes:
+* The current release of Posit Publisher only supports a single configuration
+  file (`default.toml`).
+* You can exclude files from the deployment by creating a `.positignore` file.
+  It's like a `.gitignore` file and can occur anywhere in your project directory
+  or a sub-directory, and can contain wildcards. The file list grays out ignored
+  files and provides details if you hover over them.
+
+Click the **+** above **Add a New Deployment** to make a new deployment of your
+project. Choose an account/server and give the deployment a name. You can have
+more than one deployment. For example, `staging` and `production`.
+
+<p><img width="400px" src="https://cdn.posit.co/publisher/docs/images/ui-new-deployment.png"/></p>
+
+Next, you'll get a chance to review everything before you deploy: the target
+server, contents of the configuration file, and files to be deployed.
+
+<p><img width="400px" src="https://cdn.posit.co/publisher/docs/images/ui-pre-deployment.png"/></p>
+
+Click **Deploy**.
+
+You can see the progress of your deployment:
+
+<p><img width="400px" src="https://cdn.posit.co/publisher/docs/images/ui-deploying.png"/></p>
+
+
+Click the **View summarized deployment logs** link to see a more detailed view:
+
+<p><img width="400px" src="https://cdn.posit.co/publisher/docs/images/ui-summarized-logs.png"/></p>
+
+Click a section heading, such as **Restore Python Environment**, to see a more
+detailed view:
+
+<p><img width="400px" src="https://cdn.posit.co/publisher/docs/images/ui-summarized-logs-expanded.png"/></p>
+
+Click the **Project** link at the top of the page to return to the starting
+page. Your new deployment is there:
+
+<p><img width="400px" src="https://cdn.posit.co/publisher/docs/images/ui-project-deployed.png"/></p>
+
+Click the deployment to see details and or to re-deploy, which applies any
+updates you've made to your project source code or configuration file.
+Configuration changes since your last deployment are highlighted:
+
+<p><img width="400px" src="https://cdn.posit.co/publisher/docs/images/ui-redeploy-diff.png"/></p>