Merge pull request #1082 from choldgraf/docs-dev

dev-requirements.txt

@@ -4,3 +4,4 @@ wheel
 pytest-cov
 pre-commit
 requests_mock
+conda-lock

docs/doc-requirements.txt

@@ -1,4 +1,4 @@
 sphinx==4.0.2
-recommonmark==0.7.1
 sphinxcontrib-autoprogram==0.1.7
 pydata-sphinx-theme==0.6.3
+myst-parser==0.15.2

docs/source/architecture.md

@@ -3,10 +3,7 @@
 This is a living document talking about the architecture of repo2docker
 from various perspectives.
 
-```eval_rst
-.. _buildpacks:
-```
-
+(buildpacks)=
 ## Buildpacks
 
 The **buildpack** concept comes from [Heroku](https://devcenter.heroku.com/articles/buildpacks)

docs/source/conf.py

@@ -1,37 +1,9 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-#
-# repo2docker documentation build configuration file, created by
-# sphinx-quickstart on Fri Jun  2 13:00:51 2017.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
-
 # -- General configuration ------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#
-# needs_sphinx = '1.0'
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.extlinks", "sphinxcontrib.autoprogram", "recommonmark"]
+extensions = ["sphinx.ext.extlinks", "sphinxcontrib.autoprogram", "myst_parser"]
 
 extlinks = {
     "issue": ("https://github.com/jupyterhub/repo2docker/issues/%s", "Issue #"),
@@ -43,15 +15,8 @@ extlinks = {
 templates_path = ["_templates"]
 
 
-from recommonmark.transform import AutoStructify
-
-
 def setup(app):
     app.add_css_file("custom.css")  # may also be a URL
-    app.add_config_value(
-        "recommonmark_config", {"auto_toc_tree_section": "Contents"}, True
-    )
-    app.add_transform(AutoStructify)
 
 
 # The suffix(es) of source filenames.
@@ -108,9 +73,12 @@ pygments_style = "sphinx"
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
-# repo2docker Logo
-html_logo = "_static/images/logo.png"
-html_favicon = "_static/images/favicon.ico"
+# MyST configuration
+
+myst_enable_extensions = [
+    "colon_fence",
+]
+
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -118,6 +86,8 @@ html_favicon = "_static/images/favicon.ico"
 # a list of builtin themes.
 #
 html_theme = "pydata_sphinx_theme"
+html_logo = "_static/images/logo.png"
+html_favicon = "_static/images/favicon.ico"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/contributing/contributing.md

@@ -91,6 +91,7 @@ These are not hard rules to be enforced by 🚓 but they are suggestions written
   Wait patiently for a reviewer to merge the PR.
   (Remember that **someone else** must merge your PR, even if you have the admin rights to do so.)
 
+(contributing:local-dev)=
 ## Setting up for Local Development
 
 To develop & test repo2docker locally, you need:

docs/source/contributing/tasks.md

@@ -4,6 +4,13 @@ These are some common tasks to be done as a part of developing
 and maintaining repo2docker. If you'd like more guidance for how
 to do these things, reach out in the [JupyterHub Gitter channel](https://gitter.im/jupyterhub/jupyterhub).
 
+:::{admonition} Set up your development environment first!
+:class: tip
+Before attempting most tasks, follow the directions to [set up your development environment](contributing:local-dev).
+
+Though note that many of these tasks do **not** require Docker.
+:::
+
 ## Running tests
 
 We have a lot of tests for various cases supported by repo2docker in the `tests/`
@@ -51,13 +58,12 @@ all dependencies will have the exact same version installed at all times.
 To update one of the dependencies shared across all `repo2docker` builds, you
 must follow these steps (with more detailed information in the sections below):
 
-1. Make sure you have [Docker](https://www.docker.com/) running on your computer
-2. Bump the version numbers of the dependencies you want to update in the `conda` environment ([link](https://github.com/jupyterhub/repo2docker/blob/HEAD/CONTRIBUTING.md#conda-dependencies))
-3. Make a pull request with your changes ([link](https://github.com/jupyterhub/repo2docker/blob/HEAD/CONTRIBUTING.md#make-a-pull-request))
+1. Bump the version numbers of the dependencies you want to update in the `conda` environment ([link](tasks:conda-dependencies)) 
+2. Make a pull request with your changes ([link](https://github.com/jupyterhub/repo2docker/blob/HEAD/CONTRIBUTING.md#make-a-pull-request))
 
 See the subsections below for more detailed instructions.
 
-
+(tasks:conda-dependencies)=
 ### Conda dependencies
 
 1. There are two files related to conda dependencies. Edit as needed.
@@ -83,36 +89,27 @@ See the subsections below for more detailed instructions.
    python freeze.py
    ```
 
-   This script will resolve dependencies and write them to the respective `.frozen.yml`
-   files. You will need `docker` installed to run this script.
+   This script will resolve dependencies and write them to the respective `.lock`
+   files.
 
-3. After the freeze script finishes, a number of files will have been created.
-   Commit the following subset of files to git:
+3. After the freeze script finishes, a number of files will have been **modified**.
+   They roughly follow this pattern:
 
-    ```
-    repo2docker/buildpacks/conda/environment.yml
-    repo2docker/buildpacks/conda/environment.frozen.yml
-    repo2docker/buildpacks/conda/environment.py-2.7.yml
-    repo2docker/buildpacks/conda/environment.py-2.7.frozen.yml
-    repo2docker/buildpacks/conda/environment.py-3.5.frozen.yml
-    repo2docker/buildpacks/conda/environment.py-3.6.frozen.yml
-    ```
+   ```
+   repo2docker/buildpacks/conda/environment*
+   ```
 
-5. Make a pull request; see details below.
+   You should **commit all modified files** to git.
 
-6. Once the pull request is approved (but not yet merged), Update the
+4. Make a Pull Request to the `jupyterhub/repo2docker` repository, with a description
+   of what versions were bumped / what new packages were added and why. If you fix a
+   bug or add new functionality consider adding a new test to prevent the bug from
+   coming back/the feature breaking in the future.
+
+5. Once the pull request is approved (but not yet merged), Update the
    change log (details below) and commit the change log, then update
    the pull request.
 
-
-### Make a Pull Request
-
-Once you've made the commit, please make a Pull Request to the `jupyterhub/repo2docker`
-repository, with a description of what versions were bumped / what new packages were
-added and why. If you fix a bug or add new functionality consider adding a new
-test to prevent the bug from coming back/the feature breaking in the future.
-
-
 ## Creating a Release
 
 We make a release of whatever is on `main` every month. We use "calendar versioning".