docs: add instructions for running the documentation site locally (google#4818)

This PR updates `docs/README.md` to provide clearer instructions for
contributors to run and test the documentation site locally in docker or
natively.

To run documentation site in docker, this PR introduces
`docs/docs.Dockerfile` to allow consistent local documentation serving
without requiring a local Ruby environment.

Author: cuixq

docs/README.md

@@ -1,6 +1,35 @@
-# OpenAPI generation
+# README
 
-## Prerequisites
+The [OSV.dev docs](https://osv.dev/docs) are hosted on [GitHub Pages](https://pages.github.com/).
+
+## Running docs locally (docker)
+
+You can run the docs locally consistently through docker. From the `docs` directory, run:
+
+```bash
+docker build -t osvdev-docs -f docs.Dockerfile .
+docker run -p 4000:4000 osvdev-docs
+```
+
+## Running docs locally (native)
+
+To run the docs locally:
+
+- Install `ruby (>= 3.1.0)`. This should come with `bundler`.
+  - On Debian, you need to install them separately:
+    - `ruby`
+    - `ruby-bundler`
+- In this directory:
+  - `bundle install`
+  - `bundle exec jekyll serve`
+
+Here's the full documentation on GitHub for [running Jekyll locally].
+
+[running Jekyll locally]: https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll#building-your-site-locally
+
+## OpenAPI generation
+
+### Prerequisites
 
 Install `protoc` for your platform:
 
@@ -28,8 +57,8 @@ To install the protobuf service converter, run:
 go mod download
 ```
 
-## Generation
+### Generation
 
-```
+```bash
 python3 ./build_swagger.py
 ```

docs/docs.Dockerfile

@@ -0,0 +1,22 @@
+# Use an official Ruby runtime as a parent image.
+FROM ruby:3
+
+# Set the working directory in the container.
+WORKDIR /usr/src/app
+
+# Copy the Gemfile and Gemfile.lock, and the bundle config.
+# This is done first to leverage Docker's layer caching.
+COPY ./Gemfile* ./
+
+# Install the dependencies.
+RUN bundle install
+
+# Copy the rest of the documentation files.
+COPY ./ ./
+
+# Expose port 4000 for the Jekyll server.
+EXPOSE 4000
+
+# The command to run when the container starts.
+# --host 0.0.0.0 is important to make the server accessible from outside the container.
+CMD ["bundle", "exec", "jekyll", "serve", "--host", "0.0.0.0"]