Skip to content

Commit

Permalink
Merge pull request #292 from rstudio/mm-mkdocs
Browse files Browse the repository at this point in the history 
Use mkdocs to build the docs
  • Loading branch information
@mmarchetti
mmarchetti authored May 25, 2021
2 parents 0850988 + 2a69a2c commit dcffb4a
Show file tree
Hide file tree
Showing 33 changed files with 1,210 additions and 814 deletions.
5 changes: 3 additions & 2 deletions .github/workflows/main.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,12 +155,13 @@ jobs:
needs: test
runs-on: ubuntu-latest
steps:
- uses: extractions/setup-just@v1
- uses: actions/checkout@v2
- run: make docs-build
- run: just docs/ image build
- uses: actions/upload-artifact@v2
with:
name: docs
path: docs/out/
path: docs/site/
- uses: aws-actions/configure-aws-credentials@v1
with:
aws-access-key-id: ${{ secrets.AWS_ID }}
Expand Down
262 changes: 2 additions & 260 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,264 +14,6 @@ Connect](https://www.rstudio.com/products/connect/).
- [RStudio Connect](https://www.rstudio.com/products/connect/download-commercial/) v1.7.0
or higher, configured with Python support.

If using `conda`, `pip` and `wheel` should already be installed.
# Documentation

# Installation

If you are installing `rsconnect-jupyter` for use in Jupyterhub, please see the
[Jupyterhub](#installation-in-jupyterhub) section below.

We recommend working within a `virtualenv`. If you
are unfamiliar, these commands create and activate a `virtualenv`
at `/my/path`:

```bash
pip install virtualenv
virtualenv /my/path
source /my/path/bin/activate
```

Install Jupyter inside the `virtualenv`:
```bash
pip install jupyter
```

> Note: be sure to run Jupyter from the virtual environment, not from a global
> installation.
Install the `rsconnect-jupyter` package with the following command:

```bash
pip install rsconnect_jupyter
```

Enable the `rsconnect-jupyter` extension with the following commands:

```bash
# Install `rsconnect-jupyter` as a jupyter extension
jupyter-nbextension install --sys-prefix --py rsconnect_jupyter

# Enable JavaScript extension
jupyter-nbextension enable --sys-prefix --py rsconnect_jupyter

# Enable Python extension
jupyter-serverextension enable --sys-prefix --py rsconnect_jupyter
```

Note: The above commands only need to be run once when installing
`rsconnect_jupyter`.

Note: In order to deploy content, you will need at least the
[rsconnect-python](https://github.com/rstudio/rsconnect-python) package
in every kernel you plan to deploy from.

Note: If you run into an issue during installation please let us know by filing
a bug [here](https://github.com/rstudio/rsconnect-jupyter/issues).

# Uninstalling

First disable and remove the `rsconnect-jupyter` notebook extension:

```bash
# Disable Python extensions found in `rsconnect-jupyter`
jupyter-serverextension disable --sys-prefix --py rsconnect_jupyter

# Remove JavaScript extension
jupyter-nbextension uninstall --sys-prefix --py rsconnect_jupyter
```

Finally, uninstall the `rsconnect-jupyter` python package:

```bash
pip uninstall rsconnect_jupyter
```

# Upgrading

To upgrade `rsconnect-jupyter`, first uninstall the extension and then
re-install it.

# Usage

Open a notebook and click the blue icon and select `Publish to RStudio Connect`
to publish the current notebook to RStudio Connect.

![blue toolbar icon used for publishing the notebook](docs/images/publish-icon.gif)

### Entering server information

If this is your first time publishing a notebook, you will be
prompted to enter the location and a nickname for the RStudio Connect
server.

You will also be prompted to enter your API Key. See the [RStudio Connect User
Guide](http://docs.rstudio.com/connect/user/api-keys.html) for
instructions on generating API Keys for your user.

When you click the Add Server button, `rsconnect-jupyter` will send a request
to the RStudio Connect server to verify that it can be reached via the requested
URL and that the API key is valid.

If your RStudio Connect server was configured with a self-signed certificate
(or other certificate that computer hosting your Jupyter notebook server does
not trust), the attempt to contact RStudio Connect may fail with a
TLS-related error. You have multiple options in this case, depending on your needs:

1. If your RStudio Connect Administrator can give you the Certificate Authority (CA)
Bundle for your RStudio Connect server, ask your Jupyter Administrator if it
can be added to the trusted system store.

2. If the CA Bundle cannot be added to the trusted system store, you may select
`Upload TLS Certificate Bundle` to upload the bundle to Jupyter, which will verify
your secure connection to RStudio Connect.

3. If you cannot obtain the CA bundle, you can disable TLS verification completely
by selecting the `Disable TLS Certificate Verification` box. Your connection to
RStudio Connect will still be encrypted, but you will not be able to verify the
identity of the RStudio Connect server.

![initial dialog that prompts for the location of RStudio Connect](docs/images/add-dialog.png)

### Publishing options

![publish dialog](docs/images/manage.png)

There are two different publication modes. Selecting `Publish finished document only` will
publish an HTML snapshot of the notebook to RStudio Connect. HTML snapshots are static and
cannot be scheduled or re-run on the RStudio Connect server.

If you select `Publish document with source code`, the notebook file and a list of the Python
packages installed in your environment will be sent to RStudio Connect. This enables RStudio
Connect to recreate the environment and re-run the notebook at a later time.

#### Additional Files

If your notebook needs some external file in order to render, add the file using the
`Select Files` button. You can select any file within the notebook folder. However,
these files may not be made available to users after render.

#### Environment detection with pip

The list of packages sent along with the notebook comes from the python
environment where the notebook kernel is running. In order for environment
inspection to work, the `rsconnect-jupyter` package must be installed in the
kernel environment; that is, the environment where the `ipykernel` package is
installed. In most cases that will be the same as the notebook server
environment where `jupyter` is installed.

The command `pip freeze` will be used to inspect the environment. The output
of `pip freeze` lists all packages currently installed, as well as their
versions, which enables RStudio Connect to recreate the same environment.

### Generating Manifests for git Publishing

RStudio Connect can poll git repositories for deployable content and update
as you add new commits to your repository. In order to be deployable, a
directory must have a valid `manifest.json`. Python content should also have
some kind of environment file (i.e.: `requirements.txt`) in order to be able
to restore the package set in your current environment.

![Deployment drop-down menu showing "Publish to Connect" and "Create Manifest for git Publishing"](docs/images/deploy-options.png)

To begin, select `Create Manifest for git Publishing`.

![Dialog titled "Create Manifest" explaining the manifest creation process with "Cancel" and "Create Manifest" options](docs/images/git-backed.png)

When you click `Create Manifest`, a `manifest.json` and `requirements.txt`
will be generated for the current notebook using your current environment,
if they do not exist. If they do exist, you will be presented with a message
informing you of this fact. If you need to regenerate the files, delete them
in the Jupyter UI or using the console, then repeat this process.

For more information on git publishing, see the
[RStudio Connect User Guide](https://docs.rstudio.com/connect/user/git-backed.html#git-backed-publishing)

### Handling conflicts
If content that matches your notebook's title is found on RStudio Connect, you
may choose to overwrite the existing content or create new content.

![dialog that prompts for overwriting or publishing new content](docs/images/overwrite.png)

Choosing `New location` will create a new document in RStudio Connect.
You can choose either publication mode - an HTML snapshot or a document
with source code.

Updating an existing document will not change its publication mode.


Upon successful publishing of the document a notification will be
shown in toolbar. Clicking the notification will open the published
document in the RStudio Connect server you selected in the previous
dialog.

![notification that shows the notebook was published successfully](docs/images/published.gif)

# Collaboration

To collaborate with others add them as collaborators in RStudio Connect. During
publishing they should provide their API key and will be able to choose a
content location to publish to if the notebook title is the same.

You may share notebooks if appropriate.

# Installation in JupyterHub

In JupyterHub, follow the directions [above](#installation) to install the
`rsconnect-jupyter` package into the Python environment where the Jupyter
notebook server and kernel are installed. Typically those will be the same
environment. If you've configured separate kernel environments, install the
`rsconnect-jupyter` package in the notebook server environment as well as each
kernel environment.

The exact install location depends on your Jupyterhub configuration.


## JupyterHub Example Configuration

This section presents a simple working example of a Jupyterhub configuration
with `rsconnect-jupyter` installed.

This example uses Docker, but you can install the `rsconnect-jupyter` package in
any Jupyterhub installation. Docker is not required.

Example Dockerfile:

```dockerfile
FROM jupyterhub/jupyterhub:0.9.4

# Install Jupyter notebook into the existing base conda environment
RUN conda install notebook

# Download and install rsconnect-jupyter in the same environment
# Update this to specify the desired version of the rsconnect-jupyter package,
# or pass `--build-arg VERSION=...` to docker build.
ARG VERSION=RSCONNECT_VERSION
ARG REPOSITORY=https://s3.amazonaws.com/rstudio-rsconnect-jupyter

RUN wget ${REPOSITORY}/rsconnect_jupyter-${VERSION}-py2.py3-none-any.whl
RUN pip install rsconnect_jupyter-${VERSION}-py2.py3-none-any.whl && \
jupyter-nbextension install --sys-prefix --py rsconnect_jupyter && \
jupyter-nbextension enable --sys-prefix --py rsconnect_jupyter && \
jupyter-serverextension enable --sys-prefix --py rsconnect_jupyter

# create test users
RUN useradd -m -s /bin/bash user1 && \
useradd -m -s /bin/bash user2 && \
useradd -m -s /bin/bash user3 && \
bash -c 'echo -en "password\npassword" | passwd user1' && \
bash -c 'echo -en "password\npassword" | passwd user2' && \
bash -c 'echo -en "password\npassword" | passwd user3'

CMD ["jupyterhub"]
```

Run these commands to build and start the container:
```bash
docker build -t jupyterhub:rsconnect-jupyter .
docker run --rm -p 8000:8000 --name jupyterhub jupyterhub:rsconnect-jupyter
```

Connect to Jupyterhub on http://localhost:8000 and log in as one of the test
users. From there, you can create a notebook and publish it to RStudio Connect.
Note that the current Jupyterhub docker image uses Python 3.6.5, so you will
need a compatible Python version installed on your RStudio Connect server.
See the documentation [on GitHub](docs/docs/index.md) or on [docs.rstudio.com](https://docs.rstudio.com/rsconnect-jupyter/).
4 changes: 4 additions & 0 deletions docs/.gitignore
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# mkdocs output directory
site
# copy of primary jupyter.md
docs/jupyter.md
23 changes: 23 additions & 0 deletions docs/Dockerfile
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Using dated tags from https://hub.docker.com/_/ubuntu/
FROM ubuntu:bionic-20201119
MAINTAINER RStudio Connect <[email protected]>

# Configure apt-get to use the mirror in us-east-1 instead of the Docker default of archive.ubuntu.com
RUN sed -i "s/archive.ubuntu.com/us-east-1.ec2.archive.ubuntu.com/g" /etc/apt/sources.list

# git is used to examine the repository and compute product version.
RUN export DEBIAN_FRONTEND=noninteractive && \
apt-get update && \
apt-get install -y \
git \
python3-pip && \
rm -rf /var/lib/apt/lists/*

# Needed with Python3 mkdocs.
# https://click.palletsprojects.com/en/7.x/python3/
ENV LC_ALL C.UTF-8
ENV LANG C.UTF-8

COPY requirements.txt requirements.txt
RUN pip3 install -r requirements.txt && \
rm -f requirements.txt
30 changes: 30 additions & 0 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# RStudio Connect Jupyter User Guide

This directory contains the RStudio Connect: Jupyter User Guide. We use
[mkdocs-1.0.4](https://www.mkdocs.org) to build this guide.

The Jupyter User Guide is geared towards the people who will publish Jupyter Notebooks to RStudio Connect.

## Docker

The `rsconnect-jupyter-docs` Docker image is used to produce our
documentation. We use a number of plugins and extensions; use the Docker image
rather than a local `mkdocs` installation.

Create the image:
```bash
just image
```

Build documentation:

```bash
just build
```

Launch an auto-reloading documentation server at http://localhost:8001 with
the command:

```bash
just watch
```
19 changes: 0 additions & 19 deletions docs/build-doc.sh
View file

This file was deleted.

Loading

0 comments on commit dcffb4a

Please sign in to comment.