Merge pull request #6402 from shaneknapp/update-docs-dev-reqs

update docs with mention of dev-requirements.txt + extra formatting fixes

README.md

@@ -19,7 +19,18 @@ or from links in the deployment's `image/README.md`
 The `staging` branch always reflects the state of the [staging JupyterHub](http://staging.datahub.berkeley.edu),
 and the `prod` branch reflects the state of the [production JupyterHub](http://datahub.berkeley.edu).
 
+## Installing the required python packages for working with datahub
+
+In the root directory of this repo, install `dev-requirements.txt` with the
+following command:  `pip install -r dev-requirements.txt`.  This will install
+the base python packages that are required to perform the tasks associated with
+editing, testing, building and deploying hubs.
+
+The other python package definition file, `requirements.txt` is used solely by
+our Github Actions CI/CD pipeline.
+
 ## Setting up your fork and clones
+
 First, go to your [github profile settings](https://github.com/settings/keys)
 and make sure you have an SSH key uploaded.
 
@@ -59,29 +70,36 @@ git rebase upstream/staging && \
 git push origin staging
 ```
 
-
 ## Procedure
 
 When developing for this deployment, always work in a fork of this repo.
 You should also make sure that your repo is up-to-date with this one prior
 to making changes. This is because other contributors may have pushed changes
 after you last synced with this repo but before you upstreamed your changes.
 
+### Syncing your repo
+
+The following commands will sync the local clone of your fork with `upstream`:
 ```
 git checkout staging && \
 git fetch --prune --all && \
 git rebase upstream/staging && \
 git push origin staging
 ```
 
-To create a new branch and switch to it, run the following command:
+### Creating a feature branch
+
+To create a new feature branch and switch to it, run the following command:
 ```
 git checkout -b <branch name>
 ```
 
+### Checking the status and diffs of your local work
+
 After you make your changes, you can use the following commands to see
 what's been modified and check out the diffs:  `git status` and `git diff`.
 
+### Adding, committing and pushing changes
 
 When you're ready to push these changes, first you'll need to stage them for a
 commit:
@@ -99,6 +117,8 @@ Now push to your fork:
 git push origin <branch name>
 ```
 
+### Creating a pull request
+
 Once you've pushed to your fork, you can go to the
 [Datahub repo](https://github.com/berkeley-dsep-infra/datahub) and there
 should be a big green button on the top that says `Compare and pull request`.

docs/admins/howto/calendar-scaler.qmd

@@ -91,7 +91,7 @@ can run the following commands to create one:
 
 ``` bash
 conda create -ny scalertest python=3.11
-pip install -r requirements.txt
+pip install -r images/node-placeholder-scaler/requirements.txt
 ```
 
 Any changes to the scaler code will require you to run

docs/admins/howto/new-hub.qmd

@@ -9,7 +9,8 @@ aliases:
 The major reasons for making a new hub are:
 
 1. A new course wants to join the Berkeley DataHub community.
-2. One of your *students* are course staff in another course and have *elevated access*, enabling them to see other students' work.
+2. One of your *students* are course staff in another course and have
+   *elevated access*, enabling them to see other students' work.
 3. You want to use a different kind of authenticator.
 4. You are running in a different cloud, or using a different billing
    account.
@@ -25,11 +26,15 @@ Please let us know if you have some other justification for creating a new hub.
 
 Working installs of the following utilities:
 
-  -   [sops](https://github.com/mozilla/sops/releases)
-  -   [hubploy](https://hubploy.readthedocs.io/en/latest/index.html)
+  -   [chartpress](https://pypi.org/project/chartpress/)
+  -   [cookiecutter](https://pypi.org/project/cookiecutter/)
   -   [gcloud](https://cloud.google.com/sdk/docs/install)
+  -   [hubploy](https://github.com/berkeley-dsep-infra/hubploy)
   -   [kubectl](https://kubernetes.io/docs/tasks/tools/)
-  -   [cookiecutter](https://github.com/audreyr/cookiecutter)
+  -   [sops](https://github.com/mozilla/sops/releases)
+
+The easiest way to install `chartpress`, `cookiecutter` and `hubploy` is to
+run `pip install -r dev-requirements.txt` from the root of the `datahub` repo.
 
 Proper access to the following systems:
 
@@ -53,7 +58,7 @@ will be required for the course. Typically, there are three general
 Small courses will usually have one or two assignments per semester, and
 may only have 20 or fewer users.
 
-General courses have up to \~500 users, but don't have large amount of
+General courses have up to ~500 users, but don't have large amount of
 data or require upgraded compute resources.
 
 Heavy usage courses can potentially have thousands of users, require