Define high-level organizational structure and re-organize into 2-level structure

CONTRIBUTING.md

@@ -1,81 +1,3 @@
 # Contributing to this repository
 
-Most of this repository is structured for **Sphinx**, a documentation engine in Python.
-
-## Build the documentation locally
-
-The easiest way to build the documentation in this repository is to use `nox`, a tool for quickly building environments and running commands within them.
-This ensures that your environment has all the dependencies needed to build the documentation.
-
-To do so, follow these steps:
-
-1. Install `nox`
-
-   ```
-   pip install nox
-   ```
-2. Build the documentation:
-
-   ```
-   nox -s docs_build
-   ```
-
-This should create a local environment in a `.nox` folder, build the documentation (as specified in the `noxfile.py` configuration), and the output will be in `_build/html`.
-
-To build live documentation that updates when you update local files, run the following command:
-
-```
-nox -s docs_live
-```
-
-## Pre-populate the FreshDesk Help widget
-
-We use a [FreshDesk Help Widget](https://support.freshdesk.com/support/solutions/articles/239273-set-up-your-help-widget) to let users quickly submit support tickets from our documentation.
-This is the little widget in the bottom-right that you can click on.
-
-Configuration for the JavaScript that loads this widget is in our `conf.py` file.
-See the `widget_embed_code` section.
-
-### Create a button to make the widget pop up
-
-Trigger the Help widget by calling the `openWidget()` function in JavaScript.
-You can attach it to a button by embedding some raw HTML in MyST Markdown like so:
-
-```html
-<button onclick="openWidget()">
-   Click here to open a support ticket
-</button>
-```
-
-<button onclick="openWidget()">
-   Click here to open a support ticket
-</button>
-
-### Pre-fill parts of the support widget
-
-You can configure the button to pre-populate fields for the user so that they can ask make their request more quickly.
-To do so, use `key:"value"` pairs in the call to `openWidget()`.
-
-See the `widget_embed_code` section of `conf.py` for the list of possible field names.
-
-The example below populates a few extra fields:
-
-```html
-<button onclick="openWidget({name:'Jo the Jovyan', description:'This is a cool feature!', type: 'Feature Request'})">
-   Click here to open a support ticket
-</button>
-````
-
-<button onclick="openWidget({name:'Jo the Jovyan', description:'This is a cool feature!', type: 'Feature Request'})">
-   Click here to open a support ticket
-</button>
-
-:::{admonition} Things to pay attention to:
-
-- **Note curly brackets!** You need to give the `key:val` pairs inside curly brackets!
-- **Type must exactly match a dropdown option**. If you get the case, spacing, etc wrong, then no option will be selected.
-:::
-
-## Review and merging guidelines
-
-See the [2i2c team guidelines for reviewing and merging](https://infrastructure.2i2c.org/contributing/code-review/#review-and-merge-guidelines-for-2i2c-engineers). Use your best judgment!
+For contributing, see the [getting started guide](./contribute/get-started.md) and the [contributing overview](./contribute/overview.md).

admin/community/index.md

@@ -0,0 +1,7 @@
+# Community management
+
+These sections cover operational tasks for managing your community's hub, including running events and workshops.
+
+```{toctree}
+events
+```

admin/howto/environment/customize.md → admin/environment/customize.md

@@ -41,7 +41,7 @@ Follow these steps any time you need to update the environment image that is use
 
 1. Open a [2i2c support ticket](https://docs.2i2c.org/support/) to request an update to your hub with the new custom image.
 
-   ```{image} media/open-support-ticket.png
+   ```{image} images/open-support-ticket.png
    :alt: Screenshot of 2i2c support ticket.
    ```
 
@@ -58,7 +58,7 @@ To add multiple environments for your hub, take these steps:
 
 1. Follow the steps in [](environment:image) for each environment you wish to offer your hub's users.
    You should have one repository per environment, and each one should push to a Docker image registry via the repo2docker action.
-2. [Open a support request](../../../support.md) requesting that your hub be set up to serve multiple user environments.
+2. [Open a support request](../../support.md) requesting that your hub be set up to serve multiple user environments.
    A 2i2c engineer will assist you in configuring the hub to set up multiple environments.
 
 (image-building-setup)=

admin/howto/environment/defaults.md → admin/environment/defaults.md

@@ -28,7 +28,7 @@ The [original single-document interface](https://jupyter-notebook.readthedocs.io
 ### JupyterLab
 
 
-```{figure} ../../../images/jupyterlab.png
+```{figure} images/jupyterlab.png
 :alt: JupyterLab layout
 ```
 
@@ -38,12 +38,12 @@ research organizations use this.
 
 ### RStudio
 
-```{figure} ../../../images/rstudio.png
+```{figure} images/rstudio.png
 :alt: RStudio
 ```
 
 [RStudio](https://rstudio.com) is an IDE for R, created by the RStudio company.
 
 ## Ask for changes to the default environment
 
-If you are using the default environment, and think that one or two packages should be installed by default on it, please [send a support request](../../../support.md) and request an update to the default environment.
+If you are using the default environment, and think that one or two packages should be installed by default on it, please [send a support request](../../support.md) and request an update to the default environment.

admin/howto/environment/hub-user-image-template-guide.md → admin/environment/hub-user-image-template-guide.md

@@ -10,7 +10,7 @@ Create a new repository for your user image from the [`hub-user-image-template`]
 1. Go to the [`hub-user-image-template`](https://github.com/2i2c-org/hub-user-image-template) repository.
 2. Click the {guilabel}`Use this template` button located at the top of this repository's GitHub page.
 
-   ```{figure} ../../../images/use-template.png
+   ```{figure} images/use-template.png
    :alt: Use this template
    ```
 3. This will generate a **copy** of the repository that you can modify as you wish.
@@ -31,7 +31,7 @@ When you have completed these steps, you should have:
   - **`QUAY_USERNAME`**: the user name of the `quay.io` robot account
   - **`QUAY_PASSWORD`**: the password of the `quay.io` robot account
 
-  ```{figure} ../../../images/secrets.png
+  ```{figure} images/secrets.png
   :alt: Secrets
   ```
 
@@ -53,19 +53,19 @@ To enable pushing to the appropriate quay.io repository, edit line 47 of [build.
 2. Replace `<quay-username>/<repository-name>` with the info of the `quay.io` repository created at step 2
 3. Commit the changes you've made to `build.yaml`
 
-```{figure} ../../../images/image-name-in-build-workflow.png
+```{figure} images/image-name-in-build-workflow.png
 :alt: IMAGE_NAME
 ```
 
 You can checkout the logs of this GitHub Workflow via the Github Actions tab on your image repository.
 
-```{figure} ../../../images/build-workflow.png
+```{figure} images/build-workflow.png
 :alt: Build workflow
 ```
 
 If you are triggering this action by merging a PR or directly pushing to the main branch, you should look at the Github Actions tab and this will show a `pushing quay.io/...` message, followed by the image name and tag like in the image below.
 
-```{figure} ../../../images/pushing-to-registry-job-step.png
+```{figure} images/pushing-to-registry-job-step.png
 :alt: Build logs
 ```
 
@@ -108,7 +108,7 @@ In order to be able to pull the image you need to make sure that your repository
    This is usually **under the latest tag**.
    Use this to find your image name - `quay.io/<quay-username>/<repository-name>:<tag>`.
 
-   ```{figure} ../../../images/coessing-image-quay.png
+   ```{figure} images/coessing-image-quay.png
    :alt: Tags list example
    ```
 2. Modify your hub's configuration to use the updated image Put the image tag you constructed in a previous step into the User docker image text box. Note quay web urls look like `quay.io/repository/2i2c/coessing-image`, but the docker image name in configurator **should not** include the repository part of the URL e.g. `quay.io/2i2c/coessing-image:55adca9b2caa`.

admin/howto/environment/interfaces.md → admin/environment/interfaces.md

@@ -5,12 +5,10 @@ configured environment with base libraries, user interfaces and
 languages installed. This allows them to start working immediately,
 without having to install packages themselves.
 
-(environment/custom)=
 ## Customize your user environment
 
 While all hubs [come with a default environment](environment/default), it is possible to create a custom user environment for the hub. Here are a few ways that you can do this.
 
-(environment:image)=
 ### Create your own image
 
 Our hubs use [software containers](https://www.docker.com/resources/what-container/) to enable a reproducible 
@@ -50,60 +48,13 @@ To add multiple environments for your hub, take these steps:
 
 1. Follow the steps in [](environment:image) for each environment you wish to offer your hub's users.
    You should have one repository per environment, and each one should push to a Docker image registry via the repo2docker action.
-2. [Open a support request](../../../support.md) requesting that your hub be set up to serve multiple user environments.
+2. [Open a support request](../../support.md) requesting that your hub be set up to serve multiple user environments.
    A 2i2c engineer will assist you in configuring the hub to set up multiple environments.
 
-(environment/default)=
 ## The default user environment
 
-The default environment for all community hubs is defined [in this
-repository](https://github.com/2i2c-org/2i2c-hubs-image).
+For detailed information about the default environment and user interfaces available on 2i2c hubs, see [](defaults.md).
 
-It is configured with the following:
-
-- **Python packages**: defined in [this `requirements.txt`
-  file](https://github.com/2i2c-org/2i2c-hubs-image/blob/main/requirements.txt). Many common scientific python packages are installed here.
-- **R packages**: installed from [this `install.R`
-  file](https://github.com/2i2c-org/2i2c-hubs-image/blob/main/install.R).
-- **Data science interfaces**: many popular data science user interfaces are installed:
-  - [Classic Jupyter Notebook](https://github.com/jupyter/notebook/)
-  - [JupyterLab](https://github.com/jupyterlab/jupyterlab/)
-  - [RStudio](https://rstudio.com/)
-- An Ubuntu 20.04 base image, with common utility packages installed.
-
-(environment:default-interface)=
-### Default user interfaces
-
-The 2i2c hubs offer the following user interfaces by default:
-
-#### Jupyter Notebook (Classic)
-
-The [original single-document interface](https://jupyter-notebook.readthedocs.io/en/latest/) for creating Jupyter Notebooks.
-
-#### JupyterLab
-
-
-```{figure} ../../../images/jupyterlab.png
-:alt: JupyterLab layout
-```
-
-[JupyterLab](https://github.com/jupyterlab/jupyterlab) is a more modern version of the classic Jupyter notebook from
-the Jupyter project. It is more customizable and better supports advanced use cases - particularly around [dask](https://dask.org). Many
-research organizations use this.
-
-#### RStudio
-
-```{figure} ../../../images/rstudio.png
-:alt: RStudio
-```
-
-[RStudio](https://rstudio.com) is an IDE for R, created by the RStudio company.
-
-### Ask for changes to the default environment
-
-If you are using the default environment, and think that one or two packages should be installed by default on it, please [send a support request](../../../support.md) and request an update to the default environment.
-
-(image-building-setup)=
 ## Allow users to build their own environment image
 
 Hubs can be configured to allow users to [dynamically build environment images from the JupyterHub](#user:environment-building). This provides a lightweight UI allowing users to point the hub to a GitHub repository containing the definition of the environment they wish to build.
@@ -135,7 +86,7 @@ You can replace the contents of `<your-interface>` to be one of the following:
 ### by changing the hub defaults
 
 A Hub Administrator can also configure the **default** interface that users see.
-To do so, see [the configurator interface guide](configurator:interface).
+To do so, [contact 2i2c support](../../support.md) with your request.
 
 ### by using `nbgitpuller` links
 

admin/howto/environment/update-community-image.md → admin/environment/update-community-image.md

@@ -40,7 +40,7 @@ The following summarizes [Section 3.2. Allowing robot access to a user repositor
    - *Username:* \<username\>+_<hub_name>_image_builder
    - *Password:* <64 character authorization token>.
 
-   ```{image} media/quay-robot-credentials.png
+   ```{image} images/quay-robot-credentials.png
    :alt: Screenshot showing the username and password credentials of a Robot Account on quay.io.
    ```
 
@@ -56,11 +56,11 @@ The following summarizes [Using secrets in GitHub Actions](https://docs.github.c
    - *Name*: `QUAY_USERNAME` and then paste the Robot account username from above into *Secret*
    - *Name*: `QUAY_PASSWORD` and then paste the Robot account password from above into *Secret*
 
-   ```{image} media/github-secret-username.png
+   ```{image} images/github-secret-username.png
    :alt: Screenshot of adding the QUAY_USERNAME as a GitHub secret.
    ```
 
-   ```{image} media/github-secret-password.png
+   ```{image} images/github-secret-password.png
    :alt: Screenshot of adding the QUAY_PASSWORD as a GitHub secret.
    ```
 
@@ -80,7 +80,7 @@ Once complete, under the section *Repository secrets* you should now see two row
     If your image user interface is RStudio, then you can switch to the JupyterLab interface by altering the URL to the form `https://<hub_name>.2i2c.cloud/user/<username>/lab`.
    ```
 
-1. Click the ![Git icon](media/git.svg) Git icon in the left sidebar to open the JupyterLab Git extension.
+1. Click the ![Git icon](images/git.svg) Git icon in the left sidebar to open the JupyterLab Git extension.
 
 1. Clone the forked repository from {ref}`Set up the GitHub repository and connect it to quay.io<customize-image:set-up-github>` into the hub by the clicking *Clone a Repository* button followed by entering the URL of the remote Git repository, e.g. `https://github.com/<username>/example-inherit-from-community-image.git`.
 
@@ -93,11 +93,11 @@ Once complete, under the section *Repository secrets* you should now see two row
    - Open *.github/workflows/build.yaml* and update `IMAGE_NAME` with `<username>/jupyter-scipy-xarray`
    - Open *.github/workflows/test.yaml* and update `IMAGE_NAME` with `<username>/jupyter-scipy-xarray`   
 
-   ```{image} media/edit-github-workflow.png
+   ```{image} images/edit-github-workflow.png
    :alt: Screenshot of updating the IMAGE_NAME in the GitHub workflow test.yaml file.
    ```
 
-1. From the ![Git icon](media/git.svg) JupyterLab Git extension, stage your changes to *.github/workflows/build.yaml* and *.github/workflows/test.yaml* by clicking the {octicon}`plus;1em;sd-text-info` plus symbol next to the filenames under the *Changed* section.
+1. From the ![Git icon](images/git.svg) JupyterLab Git extension, stage your changes to *.github/workflows/build.yaml* and *.github/workflows/test.yaml* by clicking the {octicon}`plus;1em;sd-text-info` plus symbol next to the filenames under the *Changed* section.
 
 1. At the bottom of the panel enter a summary message, e.g. *Update IMAGE_NAME to \<username\>/jupyter-scipy-xarray*, then commit your changes
 
@@ -107,7 +107,7 @@ Once complete, under the section *Repository secrets* you should now see two row
 
    If you see the following dialog box,
 
-   ```{image} https://github.com/czi-catalystproject/hub-champion-training/blob/main/media/episodes/transfer_data/gh-credentials.png?raw=true
+   ```{image} https://github.com/czi-catalystproject/hub-champion-training/blob/main/images/episodes/transfer_data/gh-credentials.png?raw=true
    :alt: Screenshot of Git credentials required dialog.
    :width: 65%
    :align: center
@@ -122,19 +122,19 @@ Once complete, under the section *Repository secrets* you should now see two row
 
 ### Update the base image
 
-1. From the ![Git icon](media/git.svg) JupyterLab Git extension, expand the *Current Branch* dropdown and click the *New Branch* button
+1. From the ![Git icon](images/git.svg) JupyterLab Git extension, expand the *Current Branch* dropdown and click the *New Branch* button
    - Name your branch, e.g. *add-xarray*
    - Select *main* for the *Create branch based on...* option.
 
-   ```{image} media/git-create-branch.png
+   ```{image} images/git-create-branch.png
    :alt: Screenshot of creating a new branch from the main branch using the Git JupyterLab extension.
    ```
 
 1. Edit the *Dockerfile*
    - Update the `FROM` instruction with the base image you require, e.g. `quay.io/jupyter/scipy-notebook:python-3.11`
    - For now, remove the tests by deleting the `COPY` instruction and deleting the `image-tests` folder in the file explorer.
 
-   ```{image} media/edit-dockerfile.png
+   ```{image} images/edit-dockerfile.png
    :alt: Screenshot of updating the DockerFile.
    ```
 
@@ -144,7 +144,7 @@ Once complete, under the section *Repository secrets* you should now see two row
    - Specify the Python version required, e.g. `python=3.11`
    - Add the extra package(s) to install, e.g. `xarray`.
 
-   ```{image} media/edit-environment-yaml.png
+   ```{image} images/edit-environment-yaml.png
    :alt: Screenshot of updating environment.yml.
    ```
 
@@ -158,7 +158,7 @@ Once complete, under the section *Repository secrets* you should now see two row
 
 1. Open a pull request and double-check that the target branch is *\<username\>:main* (this usually defaults to the upstream repo).
 
-   ```{image} media/check-target-branch.png
+   ```{image} images/check-target-branch.png
    :alt: Screenshot of the target branch option when opening a GitHub pull request.
    ```
 
@@ -188,7 +188,7 @@ Once complete, under the section *Repository secrets* you should now see two row
 
 1. Once complete, Binder launches into a preview of your custom container hosted at *mybinder.org*.
 
-   ```{image} media/launch-mybinder.png
+   ```{image} images/launch-mybinder.png
    :alt: Screenshot of the Binder launcher.
    ```
 
@@ -212,4 +212,4 @@ Once complete, under the section *Repository secrets* you should now see two row
 
 ## Link custom image to your hub
 
-Now that your image is published, follow these instructions: [](./custom-image.md).
+Now that your image is published, follow these instructions: [](./customize.md).

admin/get-started.md

@@ -0,0 +1,20 @@
+# Get started with a new community hub
+
+Hub administrators are trusted community members who perform common administrative operations on a hub.
+
+## What you can do
+
+As a hub administrator, you can:
+
+- Customize your hub environment (software, packages, interfaces) - see {doc}`environment/index`
+- Add and remove users from your hub
+- Start and stop user servers
+- View monitoring dashboards
+
+See the other sections in this guide for more information about each of these tasks.
+
+## Getting help
+
+For infrastructure changes or configuration that requires 2i2c support, see {doc}`../support`.
+
+For more about the hub administrator role, see {doc}`../community-lead/about/shared-responsibility`.