diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..b345fe0 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,13 @@ +FROM python:3.9-slim-buster + +WORKDIR /app + +COPY requirements.txt . + +RUN pip install --no-cache-dir -r requirements.txt + +COPY . . + +EXPOSE 8000 + +CMD ["sphinx-autobuild", "docs/", "docs/_build/html/", "--host", "0.0.0.0", "--port", "8000"] \ No newline at end of file diff --git a/docs/Makefile b/Makefile similarity index 81% rename from docs/Makefile rename to Makefile index 2334647..2e73ad1 100644 --- a/docs/Makefile +++ b/Makefile @@ -1,12 +1,9 @@ -# Minimal makefile for Sphinx documentation -# - # You can set these variables from the command line, and also # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build/html/ +SOURCEDIR = ./docs/ +BUILDDIR = ./docs/_build/html/ # Put it first so that "make" without argument is like "make help". help: @@ -14,6 +11,8 @@ help: .PHONY: help Makefile +dev: + sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile diff --git a/README.md b/README.md index 006958d..67b03fb 100644 --- a/README.md +++ b/README.md @@ -7,30 +7,41 @@ The documentation will eventually support: - #14 language support - #15 generated API documentation +## Quick Start + +### Docker +With docker and docker compose installed; run the development server with +```bash +docker compose up +``` +This will serve the documentation and automatically reload on changes at [http://localhost:8000](http://loaclhost:8000) ## Local Setup -1. Install the prereqs: -- install sphinx -- install [sphinx-book-theme](https://sphinx-book-theme.readthedocs.io/en/stable/tutorials/get-started.html): `pip install sphinx-book-theme` -- install [myst-parser](https://www.sphinx-doc.org/en/master/usage/markdown.html) (used by sphinx markdown extension): `pip install myst-parser` -2. Clone the `wildme-docs` repo: `git clone https://github.com/WildMeOrg/wildbook-docs.git` - -## Build locally -To build: -1. `cd` to the `docs` directory: -2. Run the following commands: + +1. **Clone the repository:** + ```bash + git clone --depth=5 https://github.com/WildMeOrg/wildbook-docs.git + cd wildbook-docs ``` - python -m venv .venv - source .venv/bin/activate - make html +2. **Set up a virtual environment and install dependencies:** + ```bash + python -m venv venv + source venv/bin/activate + pip install -r requirements.txt ``` -3. Files will be in `docs/_build/html/` -If you aren't seeing your changes, try `make clean html` to force a complete rebuild. +### Running Locally -To see files as they will appear online, including url paths: -1. In a new terminal, `cd` to `docs/_build/html/` -2. `python -m SimpleHTTPServer` or `python3 -m http.server` -3. Open `http://localhost:8000` in your browser +1. **Start the development server (with live reload):** + ```bash + make dev + ``` + This will serve the documentation and automatically reload on changes. Open your browser to the address provided by `sphinx-autobuild` (usually `http://127.0.0.1:8000/`). + +2. **Build the documentation (for deployment):** + ```bash + make html + ``` + The static HTML files will be generated in `docs/_build/html/`. ## Contribute to docs Changes to the content of the docs are done in the `/docs` folder in the markdown files (file extension `.md`). diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..2f46c20 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,10 @@ +version: '3.8' + +services: + docs: + build: . + ports: + - "8000:8000" + volumes: + - ./docs:/app/docs + command: sphinx-autobuild docs/ docs/_build/html/ --host 0.0.0.0 --port 8000 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..b909711 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +Sphinx==8.2.3 +sphinx-book-theme==1.1.4 +myst-parser==4.0.1 +sphinx-autobuild==2025.8.25