diff --git a/README.md b/README.md index 67776c3..7af91a9 100644 --- a/README.md +++ b/README.md @@ -132,6 +132,23 @@ bundle exec rake db:drop See the [API documentation][api] for information on how to interact with the service. +## Documentation + +Necessary documentation to operate, use, maintain, and contribute to the service +is included in this repository. The majority of these documents are written in +Markdown and can be rendered directly in GitHub or you favorite IDE. However, +the documentation as a whole is meant to be converted to a static site using +[MkDocs]. + +In order to view the documentation in its intended form locally, you can use the +included docker container. Simply run the following: + +```bash +docker compose --profile docs up -d +``` + +The documentation should then be available at http://localhost:8000. + [.env]: https://github.com/codeforamerica/document-transfer-service/blob/main/sample.env [api]: ./api.md [create-key]: ./runbooks/create_auth_key.md @@ -140,6 +157,7 @@ service. [Dockerfile]: https://github.com/codeforamerica/document-transfer-service/blob/main/Dockerfile [docker compose]: https://github.com/codeforamerica/document-transfer-service/blob/main/docker-compose.yaml [Docker Desktop]: https://docs.docker.com/desktop/ +[mkdocs]: https://www.mkdocs.org/ [omz]: https://ohmyz.sh/ [ruby-version]: https://github.com/codeforamerica/document-transfer-service/blob/main/.ruby-version [rvm]: https://rvm.io/ diff --git a/docker-compose.yaml b/docker-compose.yaml index f97df50..e1d1eb6 100644 --- a/docker-compose.yaml +++ b/docker-compose.yaml @@ -46,5 +46,15 @@ services: <<: *service-defaults command: ./script/worker run + docs: + profiles: + - docs + build: + dockerfile: docs.dockerfile + ports: + - "8000:8000" + volumes: + - .:/docs + volumes: postgres: diff --git a/docs.dockerfile b/docs.dockerfile new file mode 100644 index 0000000..8c4c4a3 --- /dev/null +++ b/docs.dockerfile @@ -0,0 +1,6 @@ +FROM squidfunk/mkdocs-material:latest + +# Install PlantUML so we can render UML diagrams. +RUN pip install plantuml_markdown +RUN apk add --no-cache plantuml --repository=https://dl-cdn.alpinelinux.org/alpine/edge/community \ + && rm -rf /var/cache/apk/*