Merge pull request #97 from salvis2/doc-updates

Documentation Updates

docs/howto/hubploy-deploy-jupyterhub-repo-setup.rst

@@ -30,16 +30,16 @@ You also need the following tools installed:
 
 #. Your cloud vendor's commandline tool.
 
-   #. `Google Cloud SDK <https://cloud.google.com/sdk/>`_ for Google Cloud
-   #. `AWS CLI <https://aws.amazon.com/cli/>`_ for AWS
-   #. `Azure CLI <https://docs.microsoft.com/en-us/cli/azure/>`_ for Azure
+   * `Google Cloud SDK <https://cloud.google.com/sdk/>`_ for Google Cloud
+   * `AWS CLI <https://aws.amazon.com/cli/>`_ for AWS
+   * `Azure CLI <https://docs.microsoft.com/en-us/cli/azure/>`_ for Azure
 
 #. A local install of `helm 3 <https://helm.sh/docs/intro/install/>`_. Helm 2 is also supported, 
    but requires the same version of Helm to be present locally and on the cluster. If you are sing 
    Helm 2, you can find both versions with ``helm version``.
 
 #. A `docker environment <https://docs.docker.com/install/>`_ that you can use. This is only 
-needed when building images.
+   needed when building images.
 
 
 Step 1: Get the ``hubploy-template`` Repository
@@ -48,14 +48,14 @@ Step 1: Get the ``hubploy-template`` Repository
 There are a couple different options for acquiring the content in `this repository`_. 
 
 * Use the repository as a template. Click the "Use this template" button on the GitHub 
-   repository's page, then input your own repo name. You can then use ``git clone`` as normal to 
-   get your repository onto your local machine.
+  repository's page, then input your own repo name. You can then use ``git clone`` as normal to 
+  get your repository onto your local machine.
 
 * Fork the repository. 
 
 * Clone it directly with ``git clone https://github.com/yuvipanda/hubploy-template.git``. The 
-   disadvantage here is that you probably won't have permissions to push changes and will have to 
-   only develop locally. Not recommended.
+  disadvantage here is that you probably won't have permissions to push changes and will have to 
+  only develop locally. Not recommended.
 
 
 Step 2: Install Hubploy
@@ -91,11 +91,16 @@ Fill in the Minimum Config Details
 
 You need to find all things marked TODO and fill them in. In particular,
 
-1. ``hubploy.yaml`` needs information about where your docker registry & kubernetes cluster is, 
-   and paths to access keys as well.
-2. ``secrets/prod.yaml`` and ``secrets/staging.yaml`` require secure random keys you can generate 
+#. ``hubploy.yaml`` needs information about where your docker registry & kubernetes cluster is, 
+   and paths to access keys as well. These access key files should be in the deployment's
+   ``secret/`` folder.
+#. ``secrets/prod.yaml`` and ``secrets/staging.yaml`` require secure random keys you can generate 
    and fill in.
 
+If you are deploying onto AWS infrastructure, your access key file should look like the aws
+credentials file (usually found at ``~/.aws/credentials``). However, the profile you use *must*
+be named ``default``.
+
 If you want to try deploying to staging now, that is fine! Hub Customization can come later as you 
 try things out.
 
@@ -105,31 +110,30 @@ Hub Customizations
 
 You can customize your hub in two major ways:
 
-#. Customize the hub image. `repo2docker`_ is used to build the image, so you can put any of the `
-   supported configuration files`_ under ``deployments/<hub-image>/image``. You *must* make a git 
+#. Customize the hub image. `repo2docker`_ is used to build the image, so you can put any of the
+   `supported configuration files`_ under ``deployments/<hub-image>/image``. You *must* make a git 
    commit after modifying this for ``hubploy build <hub-name> --push --check-registry`` to work, 
    since it uses the commit hash as the image tag.
 
 #. Customize hub configuration with various YAML files.
 
-   #. ``hub/values.yaml`` is common to *all* hubs that exist in this repo (multiple hubs can live 
-   under ``deployments/``).
+   * ``hub/values.yaml`` is common to *all* hubs that exist in this repo (multiple hubs can live 
+     under ``deployments/``).
 
-   #. ``deployments/<hub-name>/config/common.yaml`` is where most of the config specific to each 
-   hub should go. Examples include memory / cpu limits, home directory definitions, etc
+   * ``deployments/<hub-name>/config/common.yaml`` is where most of the config specific to each 
+     hub should go. Examples include memory / cpu limits, home directory definitions, etc
 
-   #. ``deployments/<hub-name>/config/staging.yaml`` and 
-   ``deployments/<hub-name>/config/prod.yaml`` 
-   are files specific to the staging & prod versions of the hub. These should be *as minimal as 
-   possible*. Ideally, only DNS entries, IP addresses, should be here.
+   * ``deployments/<hub-name>/config/staging.yaml`` and 
+     ``deployments/<hub-name>/config/prod.yaml`` 
+     are files specific to the staging & prod versions of the hub. These should be *as minimal as 
+     possible*. Ideally, only DNS entries, IP addresses, should be here.
 
-   #. ``deployments/<hub-name>/secrets/staging.yaml`` and 
-   ``deployments/<hub-name>/secrets/prod.yaml`` 
-   should contain information that mustn't be public. This would be proxy / hub secret 
-   tokens, any authentication tokens you have, etc. These files *must* be protected by something 
-   like `git-crypt <https://github.com/AGWA/git-crypt>`_ or 
-   `sops <https://github.com/mozilla/sops>`_. 
-   **THIS REPO TEMPLATE DOES NOT HAVE THIS PROTECTION SET UP YET**
+   * ``deployments/<hub-name>/secrets/staging.yaml`` and 
+     ``deployments/<hub-name>/secrets/prod.yaml`` 
+     should contain information that mustn't be public. This would be proxy / hub secret 
+     tokens, any authentication tokens you have, etc. These files *must* be protected by something 
+     like `git-crypt <https://github.com/AGWA/git-crypt>`_ or 
+     `sops <https://github.com/mozilla/sops>`_.
 
 
 You can customize the staging hub, deploy it with ``hubploy deploy <hub-name> hub staging``, and 
@@ -139,17 +143,17 @@ iterate until you like how it behaves.
 Step 4: Build and Push the Image
 ================================
 
-1. Make sure tha appropriate docker credential helper is installed, so hubploy can push to the 
+#. Make sure tha appropriate docker credential helper is installed, so hubploy can push to the 
    registry you need.
 
    For AWS, you need `docker-ecr-credential-helper <https://github.com/awslabs/
    amazon-ecr-credential-helper>`_
    For Google Cloud, you need the `gcloud commandline tool <https://cloud.google.com/sdk/>`_
 
-2. Make sure you are in your repo's root directory, so hubploy can find the directory structure it 
+#. Make sure you are in your repo's root directory, so hubploy can find the directory structure it 
    expects.
 
-3. Build and push the image to the registry
+#. Build and push the image to the registry
 
    .. code:: bash
 
@@ -203,24 +207,24 @@ repository. We would eventually like to use something like
 `sops <https://github.com/mozilla/sops>`_
 but for now...
 
-1. Install git-crypt. You can get it from brew or your package manager.
+#. Install git-crypt. You can get it from brew or your package manager.
 
-2. In your repo, initialize it.
+#. In your repo, initialize it.
 
    .. code:: bash
 
       git crypt init
 
-3. In ``.gitattributes`` have the following contents:
+#. In ``.gitattributes`` have the following contents:
 
    .. code::
 
       deployments/*/secrets/** filter=git-crypt diff=git-crypt
       deployments/**/secrets/** filter=git-crypt diff=git-crypt
       support/secrets.yaml filter=git-crypt diff=git-crypt
 
-4. Make a copy of your encryption key. This will be used to decrypt the secrets. You will need to 
-share it with your CD provider, and anyone else.
+#. Make a copy of your encryption key. This will be used to decrypt the secrets. You will need to 
+   share it with your CD provider, and anyone else.
 
    .. code::
 
@@ -232,21 +236,21 @@ share it with your CD provider, and anyone else.
 Step 8: GitHub Workflows
 ========================
 
-1. Get a base64 copy of your key
+#. Get a base64 copy of your key
 
    .. code:: bash
 
       cat key | base64
 
-2. Put it as a secret named GIT_CRYPT_KEY in github secrets.
+#. Put it as a secret named GIT_CRYPT_KEY in github secrets.
 
-3. Make sure you change the `myhub` to your deployment name in the
+#. Make sure you change the `myhub` to your deployment name in the
    workflows under `.github/workflows`.
 
-4. Push to the staging branch, and check out GitHub actions, to
+#. Push to the staging branch, and check out GitHub actions, to
    see if your action goes to completion.
 
-5. If the staging action succeeds, make a PR from staging to prod,
+#. If the staging action succeeds, make a PR from staging to prod,
    and merge this PR. This should also trigger an action - see if
    this works out.
 

docs/howto/hubploy-setup-dev-environment.rst

@@ -14,20 +14,16 @@ making a custom Hubploy image for your own use or contributing to the Hubploy re
 Prerequisites
 ===========================
 
-To start, you really only need ``git`` to clone the repository. Methodology for testing Hubploy is 
-limited right now but my recommendation is that you have a working JupyterHub configuration that 
-you can try to build / deploy.
+To start, fork the `main Hubploy repository <https://github.com/yuvipanda/hubploy>`_
+and then clone your fork. This will enable easier setup for pull requests and
+independent development. Methodology for testing Hubploy is limited right now but it is
+recommendation that you have a working JupyterHub configuration so you can try to
+build and deploy.
 
 If you don't have such a configuration set up, we recommend setting one up using the 
 `hubploy template repository <https://github.com/yuvipanda/hubploy-template>`_ and following the 
-how-to on Deploying a JupyterHub with Hubploy (link later).
-
-If you don't need to push your custom Hubploy anywhere (not recommended), you can just download 
-hubploy with ``git clone https://github.com/yuvipanda/hubploy.git``.
-
-Most use-cases will require that you have a hosted repository for Hubploy, so you should fork the 
-`main Hubploy repository <https://github.com/yuvipanda/hubploy>`_ and then clone your fork 
-(recommended).
+How-To guide
+`Deploying a JupyterHub with Hubploy <https://hubploy.readthedocs.io/en/latest/howto/hubploy-deploy-jupyterhub-repo-setup.html>`_.
 
 
 Modifying Hubploy Files
@@ -41,8 +37,8 @@ should be reflected the next time you run a ``hubploy`` command.
 Using a Custom Hubploy Locally
 ==============================
 
-Hubploy can normally be installed via ``pip install hubploy``, but using a custom version of 
-Hubploy will require different installation methods.
+Hubploy can be installed via ``pip install hubploy``, but this version is very out-of-date.
+Using a custom version of Hubploy will require different installation methods.
 
 If you are just using your custom Hubploy locally, you can link it with ``pip``. Go to the top 
 folder of your ``hubploy-template`` or JupyterHub deployment repo and run::
@@ -52,6 +48,12 @@ folder of your ``hubploy-template`` or JupyterHub deployment repo and run::
 You can then make changes to your local Hubploy files and rerun Hubploy commands in the other 
 folder for quick development.
 
+`hubploy` can also be installed at any specific commit with the following line in a
+`requirements.txt` file:
+::
+
+  git+https://github.com/yuvipanda/hubploy@<commit-hash>
+
 
 Building a Custom Hubploy on DockerHub
 ======================================
@@ -92,3 +94,6 @@ Contributing to Hubploy
 
 If you have your own fork of Hubploy, and have a feature that would be generally useful, feel free 
 to join the dicussions in the Issues section or contribute a PR!
+
+For more details, see the full
+`contribution guide <https://hubploy.readthedocs.io/en/latest/reference/contribution-guide.html>`_.

docs/index.rst

@@ -4,14 +4,15 @@ HubPloy
 
 ``hubploy`` is a suite of commandline tools and an opinionated
 repository structure for continuously deploying JupyterHubs on Kubernetes (with
-`Zero to JupyterHub <https://z2jh.jupyter.org>`_).
+`Zero to JupyterHub <https://z2jh.jupyter.org>`_). Find the ``hubploy``
+`repository <https://github.com/yuvipanda/hubploy>`_ on GitHub.
 
 
 Hubploy workflow
 ================
 
 **Every change to your hub configuration must be made via a pull request
-to your git repository**. Guided by principles of `continuous deliver <https://continuousdelivery.com/>`_,
+to your git repository**. Guided by principles of `continuous delivery <https://continuousdelivery.com/>`_,
 this informs hubploy's design.
 
 Components

docs/reference/contribution-guide.rst

@@ -0,0 +1,84 @@
+==================
+Contribution Guide
+==================
+
+* `Setting up for Documentation Development`_
+* `Setting up for Hubploy Development`_
+
+
+``hubploy`` is open-source and anyone can contribute to it. We welcome
+the help! Yuvi Panda is the original author and can give GitHub contributor
+access to those who are committed to making ``hubploy`` better. You do not
+have to be a contributor on GitHub to suggest changes in
+`the Issues section <https://github.com/yuvipanda/hubploy/issues>`_ or make
+pull requests. A contributor will have to accept your changes before they become
+a part of ``hubploy``.
+
+If you don't have `git <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_
+already, install it and clone this repository.
+
+.. code:: bash
+
+   git clone https://github.com/yuvipanda/hubploy
+
+Using a
+`forking workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow>`_
+is also useful and will make seting up pull requests easier.
+
+Once you have made changes that you are ready to offer to ``hubploy``,
+make a
+`pull request <https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/about-pull-requests>`_
+to the main `hubploy repository <https://github.com/yuvipanda/hubploy>`_.
+Someone will get back to you soon on your changes.
+
+If you want to dicuss
+changes before they get onto GitHub or contact a contributor, try the
+`JupyterHub Gitter channel <https://gitter.im/jupyterhub/jupyterhub>`_.
+
+
+Setting up for Documentation Development
+========================================
+
+The ``hubploy`` documentation is automatically built on each commit
+`as configured on ReadTheDocs <https://readthedocs.org/projects/hubploy/>`_.
+Source files are in the ``docs/`` folder of the main repository.
+
+To set up your local machine for documentation development, install the
+required packages with:
+
+.. code:: bash
+
+   # From the docs/ folder
+   pip install -r doc-requirements.txt
+
+To test your updated documentation, run:
+
+.. code:: bash
+
+   # From the docs/ folder
+   make html
+
+Make sure there are no warnings or errors. From there, you can check
+the ``_build/html/`` folder and launch the ``.html`` files locally to
+check that formatting is as you expect.
+
+
+Setting up for Hubploy Development
+==================================
+
+See the How-To guide on
+`setting up a development environment <https://hubploy.readthedocs.io/en/latest/howto/hubploy-setup-dev-environment.html>`_
+for ``hubploy``.
+
+In short, you can install ``hubploy`` and its dependencies easily
+with the above guide but you will need a
+`kubernetes <https://kubernetes.io/>`_ cluster to do local deployment
+tests. Some good resources for deploying a kubernetes cluster are:
+
+#. `Zero to JupyterHub K8s <https://zero-to-jupyterhub.readthedocs.io/en/latest/>`_
+#. `AWS Terraform K8s Examples <https://github.com/pangeo-data/terraform-deploy/tree/master/aws-examples>`_
+
+You will also need to reference the section
+`Using a Custom Hubploy Locally <https://hubploy.readthedocs.io/en/latest/howto/hubploy-setup-dev-environment.html#using-a-custom-hubploy-locally>`_,
+rather than doing a default ``hubploy`` installation.
+

docs/reference/index.rst

@@ -4,4 +4,5 @@ Reference Docs Home
 
 .. toctree::
 
-   reference-hubploy-configuration-values
+   reference-hubploy-configuration-values
+   contribution-guide

docs/reference/reference-hubploy-configuration-values.rst

@@ -46,6 +46,8 @@ The various values are described below.
 images
 ======
 
+The entire ``images`` block is optional. If you don't need it, comment it out or delete it.
+
 image_name
 ----------
 

docs/topics/index.rst

@@ -5,4 +5,6 @@ Topics Home
 .. toctree::
 
    topic-directory-structure
-   topic-values-yaml-overriding
+   topic-values-yaml-overriding
+   topic-helm-versions
+

docs/topics/topic-directory-structure.rst

@@ -67,7 +67,8 @@ Hubploy takes in secrets for credentialing via the ``.cfg`` files. You can renam
 just be sure to put the proper names into ``hubploy.yaml``.
 
 The image folder can have additional files depending on how you are building the image. See more 
-in the image building how-to.
+in the image building how-to. If you are not specifying ``images`` in your ``hubploy.yaml`` file,
+the ``images/`` folder can be deleted.
 
 
 Hub Folder