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/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/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/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 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..b6602e0d 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 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".