Define high-level organizational structure and re-organize into 2-level structure (#276)

Author: choldgraf

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

community/events.md renamed to admin/community/events.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/community/index.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/customize.md renamed to admin/environment/customize.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/defaults.md renamed to admin/environment/defaults.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`.