From 7963a791acfba9cd47534f97daa3802df164b70c Mon Sep 17 00:00:00 2001
From: Jeremy Tuloup <jeremy.tuloup@gmail.com>
Date: Wed, 15 Mar 2023 07:48:05 +0100
Subject: [PATCH] Add documentation for contributing to the docs (#6771)

* Develop docs on Gitpod

* Add documentation section to the contributing docs

* Add a section for contributing from the browser

* typo fix

* fix link in contributing

* Add Gitpod badge

* fix auto activate
---
 .gitpod.yml     | 10 ++++++++++
 CONTRIBUTING.md | 26 ++++++++++++++++++++++++++
 README.md       |  1 +
 pyproject.toml  |  1 +
 4 files changed, 38 insertions(+)

diff --git a/.gitpod.yml b/.gitpod.yml
index 056ef6cc5..d73cdd088 100644
--- a/.gitpod.yml
+++ b/.gitpod.yml
@@ -43,5 +43,15 @@ tasks:
       echo "source /workspace/bin/activate-env.sh" >> ~/.bashrc
       source /workspace/bin/activate-env.sh
 
+  - name: docs
+    command: |
+      gp sync-await setup
+      sudo apt-get update
+      sudo apt install enchant-2 -y
+      wget https://github.com/jgm/pandoc/releases/download/2.14.2/pandoc-2.14.2-1-amd64.deb -O /tmp/pandoc.deb && sudo dpkg -i /tmp/pandoc.deb
+      source /workspace/bin/activate-env.sh
+      hatch run docs:build
+      hatch run docs:serve
+
 ports:
   - port: 8888
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 1c9dce8c1..1077c1297 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -152,3 +152,29 @@ automatically on save.
 
 Some of the hooks only run on CI by default, but you can invoke them by
 running with the `--hook-stage manual` argument.
+
+## Documentation
+
+First make sure you have set up a development environment as described above.
+
+Then run the following command to build the docs:
+
+```shell
+hatch run docs:build
+```
+
+In a separate terminal window, run the following command to serve the documentation:
+
+```shell
+hatch run docs:serve
+```
+
+Now open a web browser and navigate to `http://localhost:8000` to access the documentation.
+
+## Contributing from the browser
+
+Alternatively you can also contribute to Jupyter Notebook without setting up a local environment, directly from a web browser:
+
+- [Gitpod](https://gitpod.io/#https://github.com/jupyter/notebook) integration is enabled. The Gitpod config automatically builds the Jupyter Notebook application and the documentation.
+- GitHub’s [built-in editor](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files) is suitable for contributing small fixes
+- A more advanced [github.dev](https://docs.github.com/en/codespaces/the-githubdev-web-based-editor) editor can be accessed by pressing the dot (.) key while in the Jupyter Notebook GitHub repository,
diff --git a/README.md b/README.md
index c7119516e..e475ee76e 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,7 @@
 [![Documentation Status](https://readthedocs.org/projects/jupyter-notebook/badge/?version=latest)](https://jupyter-notebook.readthedocs.io/en/latest/?badge=latest)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jupyter/notebook/main?urlpath=tree)
 [![codecov](https://codecov.io/gh/jupyter/notebook/branch/main/graph/badge.svg)](https://codecov.io/gh/jupyter/notebook)
+[![Gitpod](https://img.shields.io/badge/gitpod_editor-open-blue.svg)](https://gitpod.io/#https://github.com/jupyter/notebook)
 
 The Jupyter notebook is a web-based notebook environment for interactive
 computing.
diff --git a/pyproject.toml b/pyproject.toml
index e7ea503ca..7d22dee7d 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -116,6 +116,7 @@ include = ["/notebook"]
 features = ["docs"]
 [tool.hatch.envs.docs.scripts]
 build = "make -C docs html SPHINXOPTS='-W'"
+serve = "cd docs/build/html && python -m http.server"
 
 [tool.hatch.envs.default.scripts]
 npm_pack = "jlpm lerna exec -- npm pack"