diff --git a/.travis.yml b/.travis.yml index 67f390d566..283df74d6b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,5 +7,5 @@ services: install: - make dev-env script: - - make docs + - make test/docs docs - make build-test-all DARGS="--build-arg TEST_ONLY_BUILD=1" diff --git a/Makefile b/Makefile index ff75d0582e..249a49a539 100644 --- a/Makefile +++ b/Makefile @@ -60,6 +60,9 @@ dev-env: ## install libraries required to build docs and run tests docs: ## build HTML documentation make -C docs html +test/docs: ## check links in Sphinx documentation + make -C docs linkcheck + test/%: ## run tests against a stack @TEST_IMAGE="$(OWNER)/$(notdir $@)" pytest test diff --git a/docs/_static/docker-github-settings.png b/docs/_static/docker-github-settings.png new file mode 100644 index 0000000000..8a07fe0c1b Binary files /dev/null and b/docs/_static/docker-github-settings.png differ diff --git a/docs/_static/docker-org-select.png b/docs/_static/docker-org-select.png new file mode 100644 index 0000000000..3d2a2b8ca7 Binary files /dev/null and b/docs/_static/docker-org-select.png differ diff --git a/docs/_static/docker-repo-name.png b/docs/_static/docker-repo-name.png new file mode 100644 index 0000000000..b4088f9d54 Binary files /dev/null and b/docs/_static/docker-repo-name.png differ diff --git a/docs/_static/travis-build-settings.png b/docs/_static/travis-build-settings.png new file mode 100644 index 0000000000..3d6b1a5483 Binary files /dev/null and b/docs/_static/travis-build-settings.png differ diff --git a/docs/_static/travis-enable-build.png b/docs/_static/travis-enable-build.png new file mode 100644 index 0000000000..bc5c2058c6 Binary files /dev/null and b/docs/_static/travis-enable-build.png differ diff --git a/docs/_static/travis-plus-repo.png b/docs/_static/travis-plus-repo.png new file mode 100644 index 0000000000..921b56e1b3 Binary files /dev/null and b/docs/_static/travis-plus-repo.png differ diff --git a/docs/conf.py b/docs/conf.py index a074a76ebd..3e9d800995 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -166,5 +166,7 @@ 'Miscellaneous'), ] +# -- Extension configuration ------------------------------------------------- - +# Anchors are often dynamic +linkcheck_anchors = False \ No newline at end of file diff --git a/docs/contributing/recipes.md b/docs/contributing/recipes.md index ad507e601e..55729f3fcb 100644 --- a/docs/contributing/recipes.md +++ b/docs/contributing/recipes.md @@ -5,5 +5,4 @@ We welcome contributions of [recipes](../using/recipes.html), short examples of 1. Open the `docs/using/recipes.md` source file. 2. Add a second-level Markdown heading naming your recipe at the bottom of the file (e.g., `## Add the RISE extension``) 3. Write the body of your recipe under the heading, including whatever command line, Dockerfile, links, etc. you need. -4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes. -5. Discuss changes with the maintainers and address any formatting or content issues. +4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes. Maintainers will respond and work with you to address any formatting or content issues. diff --git a/docs/contributing/stacks.md b/docs/contributing/stacks.md index 70a6a58ebf..b2db2d6557 100644 --- a/docs/contributing/stacks.md +++ b/docs/contributing/stacks.md @@ -1,13 +1,13 @@ # Community Stacks -We love to see the community create and share new Jupyter Docker images. We've created a [cookiecutter project](https://github.com/jupyter/cookiecutter-docker-stacks) and the documentation below as one way to get started defining, building, and sharing your Jupyter environments in Docker. If you choose to follow these steps, you will: +We love to see the community create and share new Jupyter Docker images. We've put together a [cookiecutter project](https://github.com/jupyter/cookiecutter-docker-stacks) and the documentation below to help you get started defining, building, and sharing your Jupyter environments in Docker. Following these steps will: 1. Setup a project on GitHub containing a Dockerfile based on either the `jupyter/base-notebook` or `jupyter/minimal-notebook` image. 2. Configure Travis CI to build and test your image when users submit pull requests to your repository. 3. Configure Docker Cloud to build and host your images for others to use. 4. Update the [list of community stacks](../using/selecting.html#community-stacks) in this documentation to include your image. -This approach mirrors how we build and share the core stack images. Again, it just one of many approaches you might choose to take to share your creations. +This approach mirrors how we build and share the core stack images. Feel free to follow it or pave your own path using alternative services and build tools. ## Creating a Project @@ -65,6 +65,47 @@ git push -u origin master ## Configuring Travis +Next, link your GitHub project to Travis CI to build your Docker image whenever you or someone else submits a pull request. + +1. Visit [https://docs.travis-ci.com/user/getting-started/#To-get-started-with-Travis-CI](https://docs.travis-ci.com/user/getting-started/#To-get-started-with-Travis-CI) and follow the instructions to add the Travis CI application to your GitHub account. +3. Visit [https://travis-ci.org](https://travis-ci.org). +4. Click the + symbol at the top of the left sidebar. + ![Travis sidebar with plus button screenshot](../_static/travis-plus-repo.png) +5. Locate your project repository either in your primary user account or in one of the organizations to which you belong. +6. Click the toggle to enable builds for the project repository. +7. Click the **Settings** button for that repository. + ![Travis enable build toggle screenshot](../_static/travis-enable-build.png) +8. Enable **Build only if .travis.yml is present** and **Build pushed pull requests**. + ![Travis build settings screenshot](../_static/travis-build-settings.png) +9. Disable **Build pushed branches**. + ## Configuring Docker Cloud +Now, configure Docker Cloud to build your stack image and push it to Docker Hub repository whenever you merge a GitHub pull request to the master branch of your project. + +1. Visit [https://cloud.docker.com/](https://cloud.docker.com/) and login. +2. Select the account or organization matching the one you entered when prompted with `stack_org` by the cookiecutter. + ![Docker account selection screenshot](../_static/docker-org-select.png) +3. Scroll to the bottom of the page and click **Create repository**. +4. Enter the name of the image matching the one you entered when prompted with `stack_name` by the cookiecutter. + ![Docker image name and description screenshot](../_static/docker-repo-name.png) +5. Enter a description for your image. +6. Click **GitHub** under the **Build Settings** and follow the prompts to connect your account if it is not already connected. +7. Select the GitHub organization and repository containing your image definition from the dropdowns. + ![Docker from GitHub automated build screenshot](../_static/docker-github-settings.png) +8. Click the **Create and Build** button. + +## Defining Your Image + +Make edits the Dockerfile in your project to add third-party libraries and configure Jupyter applications. Refer to the Dockerfiles for the core stacks (e.g., [jupyter/datascience-notebook](https://github.com/jupyter/docker-stacks/blob/master/datascience-notebook/Dockerfile)) to get a feel for what's possible and best practices. + +[Submit pull requests](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) to your project repository on GitHub. Ensure your image builds properly on Travis before merging to master. Refer to Docker Cloud for builds of your master branch that you can `docker pull`. + ## Sharing Your Image + +Finally, if you'd like to add a link to your project to this documentation site, please do the following: + +1. Clone ths [jupyter/docker-stacks](https://github.com/jupyter/docker-stacks) GitHub repository. +2. Open the `docs/using/selecting.md` source file and locate the **Community Stacks** section. +3. Add a bullet with a link to your project and a short description of what your Docker image contains. +4. [Submit a pull request](https://github.com/PointCloudLibrary/pcl/wiki/A-step-by-step-guide-on-preparing-and-submitting-a-pull-request) (PR) with your changes. Maintainers will respond and work with you to address any formatting or content issues. \ No newline at end of file