icon (blue publish icon) and select `Publish to RStudio Connect`
-to publish the current notebook to RStudio Connect.
-
-### 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.
-1. 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.
-1. 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.
-
-
-
-### Publishing options
-
-
-
-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.
+- Install rsconnect-jupyter with your virtual environment active to install and activate the plugin for that copy of Jupyter:
-
+ --8<-- "snippets/python_pkg.md"
-To begin, select `Create Manifest for git Publishing`.
+!!! important
+ Be sure to run Jupyter from this virtual environment, not from
+ another installation, or the `rsconnect-jupyter` extension will
+ not be available. To do so, you will need to activate the virtual
+ environment in each new terminal session before you run `jupyter`.
-
+---
-When you click **Create Manifest**, one of the following will happen:
+### Installing to Jupyter running on RStudio Workbench
-- If a `manifest.json` and `requirements.txt` does not exist, they will be generated for the current notebook using your current environment.
-- 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.
-
-
-
-- Choosing **New location** creates 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.
+- If you are installing `rsconnect-jupyter` to Jupyter running on RStudio Server Pro, see
+the [RStudio Server Pro documentation on Jupyter Notebooks](https://docs.rstudio.com/rsp/integration/jupyter-standalone/#4-install-jupyter-notebooks-jupyterlab-and-python-packages)
+for instructions on installing the plugin to the right location.
-
+- Once you complete the installation instructions, please return to this document for additional information such as [Upgrading](/upgrading) or [Usage](/usage) instructions.
-## 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.
+### Installation in JupyterHub
-You may share notebooks if appropriate.
+In JupyterHub, follow these directions to install the
+`rsconnect-jupyter` package into the Python environment where the Jupyter
+notebook server and kernel are installed:
-## Installation in JupyterHub
+--8<-- "snippets/python_pkg.md"
-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
+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.
+The exact install location depends on your JupyterHub configuration.
-### JupyterHub Example Configuration
+#### JupyterHub Example Configuration
-This section presents a simple working example of a Jupyterhub 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
-```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: - -Terminal
-```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. - -## Uninstalling - -- First disable and remove the `rsconnect-jupyter` notebook extension: -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: + +Terminal
+ ```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. diff --git a/docs/docs/js/custom.js b/docs/docs/js/custom.js index 8c3191ee..d7e736dc 100644 --- a/docs/docs/js/custom.js +++ b/docs/docs/js/custom.js @@ -1,16 +1,25 @@ // Terminal CSS -// Iterate all the items with class: `language-terminal` -var codehilites = document.getElementsByClassName("codehilite") -for(var i = 0; i < codehilites.length; i++) { - var codehilite = codehilites[i]; - var pre_block = codehilite.getElementsByTagName("pre")[0]; +// Modify the text to encapsulate ($,>,>>>) within one span tags +// So its not selectable - // Modify the text to encapsulate ($,>,>>>) within span tags - var terminal_regex = "^()?\\$ "; +// Iterate all the items with class: `highlight` +var highlight_divs = document.getElementsByClassName("highlight") + +for(var i = 0; i < highlight_divs.length; i++) { + var highlight = highlight_divs[i]; + var pre_block = highlight.getElementsByTagName("code")[0]; + + + // Valid regexes that will be replace + var terminal_regex = "^()?(\")?\\$ "; + var console_regex = '^()?\\$ '; var r_console_regex = '^()?> '; var python_shell_regex = '^()?>>> '; - regexs = [terminal_regex, r_console_regex, python_shell_regex] - replacements = ["$", ">", ">>>"] + regexs = [terminal_regex, console_regex, r_console_regex, python_shell_regex] + + // Replacements for each of the regex + replacements = ["$", "$", ">", ">>>"] + for (j in regexs) { var regex = regexs[j] var replacement = replacements[j] @@ -18,5 +27,6 @@ for(var i = 0; i < codehilites.length; i++) { var str = pre_block.innerHTML; str = str.replace(re, "" + replacement + " "); pre_block.innerHTML = str; + } -} +} \ No newline at end of file diff --git a/docs/docs/snippets/python_pkg.md b/docs/docs/snippets/python_pkg.md new file mode 100644 index 00000000..38046119 --- /dev/null +++ b/docs/docs/snippets/python_pkg.md @@ -0,0 +1,25 @@ +- The following commands should be run after activating the Python environment where you plan to use `jupyter`. + + - Install the `rsconnect-jupyter` package with the following command: +
icon (blue publish button) and select **Publish to RStudio Connect**
+to publish the current notebook to RStudio Connect.
+
+!!! note
+ This plugin is only for notebooks using Python kernels. Therefore, R notebooks cannot be published using this plugin.
+
+## 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) 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 certificates that the 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 administrator can give you the Certificate Authority (CA)
+ Bundle for your RStudio Connect server, ask your administrator if it
+ can be added to the trusted system store.
+1. 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.
+1. If you cannot obtain the CA bundle, you can disable TLS verification completely
+ by selecting the **Disable TLS Certificate Verification** check 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.
+
+
+
+## Publishing options
+
+There are two different publication modes:
+
+- 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.
+- 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.
+
+
+
+### Additional Files
+
+If your notebook needs some external file 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. 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. 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`) to be able
+to restore the package set in your current environment.
+
+
+
+To begin, click the **Publish** button and select **Create Manifest for git Publishing**.
+
+
+
+When you click **Create Manifest**, one of the following will happen:
+
+- If a `manifest.json` or a `requirements.txt` file does not exist, one will be generated for the current notebook using your current environment.
+- If either file exists, 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#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.
+
+
+
+- Choosing **New location** creates 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 the toolbar.
+
+Clicking the notification will open the published
+document in the RStudio Connect server you selected in the previous
+dialog.
+
+
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index e460412a..c6448a85 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -10,8 +10,12 @@ google_analytics:
- 'auto'
nav:
-- 'Introduction': 'index.md'
-
+- 'Installing': 'index.md'
+- 'Upgrading': 'upgrading.md'
+- 'Usage': 'usage.md'
+- 'Collaboration': 'collaboration.md'
+- 'Uninstalling': 'uninstalling.md'
+- 'Additional Resources': 'additional.md'
markdown_extensions:
- admonition
@@ -24,6 +28,7 @@ markdown_extensions:
- codehilite:
guess_lang: false
- pymdownx.tabbed
+ - pymdownx.details
- pymdownx.snippets:
base_path: 'docs/'
check_paths: true
@@ -36,7 +41,7 @@ plugins:
theme:
name: material
custom_dir: overrides
- logo: 'images/rstudio-logo.png'
+ logo: 'images/rstudio-logo.svg'
palette:
primary: 'white'
diff --git a/docs/overrides/partials/footer.html b/docs/overrides/partials/footer.html
index 9be29411..2a7ec2de 100644
--- a/docs/overrides/partials/footer.html
+++ b/docs/overrides/partials/footer.html
@@ -7,66 +7,55 @@