From 5589f989a22fb18f8b4309988a2f58d0a14a07c2 Mon Sep 17 00:00:00 2001 From: Michael Marchetti Date: Mon, 29 Jan 2024 11:21:00 -0500 Subject: [PATCH] first draft docs for 1.0a2 --- docs/cli.md | 102 +++++++++++++++++++++++++ docs/index.md | 63 ++++++++++++++++ docs/installation.md | 172 +++++++++++++++++++++++++++++++++++++++++++ docs/ui.md | 52 +++++++++++++ 4 files changed, 389 insertions(+) create mode 100644 docs/cli.md create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/ui.md diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 000000000..62006d39a --- /dev/null +++ b/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 +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..ffcebf76f --- /dev/null +++ b/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) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 000000000..aa4fe0b6a --- /dev/null +++ b/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`** | diff --git a/docs/ui.md b/docs/ui.md new file mode 100644 index 000000000..e78709875 --- /dev/null +++ b/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. + +

+ +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`. + +

+ +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. + +

+ +Click **Deploy**. + +You can see the progress of your deployment: + +

+ + +Click the **View summarized deployment logs** link to see a more detailed view: + +

+ +Click a section heading, such as **Restore Python Environment**, to see a more +detailed view: + +

+ +Click the **Project** link at the top of the page to return to the starting +page. Your new deployment is there: + +

+ +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: + +