From 1ffb05f02ef0a504a97f580a74231d2ca1461738 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 13 Sep 2021 09:23:27 -0700 Subject: [PATCH 1/4] Recommonmark -> MyST Parser --- docs/doc-requirements.txt | 2 +- docs/source/conf.py | 48 ++++++++------------------------------- 2 files changed, 10 insertions(+), 40 deletions(-) diff --git a/docs/doc-requirements.txt b/docs/doc-requirements.txt index c8307489..e9ab5d3a 100644 --- a/docs/doc-requirements.txt +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 1dbe92c8..f9ea70a9 100644 --- a/docs/source/conf.py +++ b/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 From 7376dfcd805e9d7e68aa02230a2d5150f279592f Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 13 Sep 2021 09:23:50 -0700 Subject: [PATCH 2/4] Clarify conda package update instructions in dev docs --- dev-requirements.txt | 1 + docs/source/architecture.md | 5 +-- docs/source/contributing/contributing.md | 1 + docs/source/contributing/tasks.md | 49 +++++++++++------------- 4 files changed, 26 insertions(+), 30 deletions(-) diff --git a/dev-requirements.txt b/dev-requirements.txt index 0157b45f..4e5996e0 100644 --- a/dev-requirements.txt +++ b/dev-requirements.txt @@ -4,3 +4,4 @@ wheel pytest-cov pre-commit requests_mock +conda-lock diff --git a/docs/source/architecture.md b/docs/source/architecture.md index 0d056ca9..15385518 100644 --- a/docs/source/architecture.md +++ b/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) diff --git a/docs/source/contributing/contributing.md b/docs/source/contributing/contributing.md index 3e333ab6..96859a6b 100644 --- a/docs/source/contributing/contributing.md +++ b/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: diff --git a/docs/source/contributing/tasks.md b/docs/source/contributing/tasks.md index 62d58f38..0a4e73fa 100644 --- a/docs/source/contributing/tasks.md +++ b/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 to **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. @@ -84,35 +90,26 @@ See the subsections below for more detailed instructions. ``` This script will resolve dependencies and write them to the respective `.frozen.yml` - files. You will need `docker` installed to run this script. + 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". From b83ebe992021a6eb902f1d8c608e60e00c940a94 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 13 Sep 2021 11:28:46 -0700 Subject: [PATCH 3/4] Update docs/source/contributing/tasks.md Co-authored-by: Simon Li --- docs/source/contributing/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/tasks.md b/docs/source/contributing/tasks.md index 0a4e73fa..0a062dc1 100644 --- a/docs/source/contributing/tasks.md +++ b/docs/source/contributing/tasks.md @@ -8,7 +8,7 @@ to do these things, reach out in the [JupyterHub Gitter channel](https://gitter. :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 to **not** require Docker. +Though note that many of these tasks do **not** require Docker. ::: ## Running tests From d2bdb9078619ee833d96c2e5a2690b3e7a7a5ace Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Mon, 13 Sep 2021 11:28:57 -0700 Subject: [PATCH 4/4] Update docs/source/contributing/tasks.md Co-authored-by: Simon Li --- docs/source/contributing/tasks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/tasks.md b/docs/source/contributing/tasks.md index 0a062dc1..b6602e0d 100644 --- a/docs/source/contributing/tasks.md +++ b/docs/source/contributing/tasks.md @@ -89,7 +89,7 @@ See the subsections below for more detailed instructions. python freeze.py ``` - This script will resolve dependencies and write them to the respective `.frozen.yml` + 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 **modified**.