Update docs install docs

Author: pmac

Makefile

@@ -30,9 +30,10 @@ help:
 	@echo "  test                           - run tests against local files"
 	@echo "  test-image                     - run tests against files in docker image"
 	@echo "  test-cdn                       - run CDN tests against TEST_DOMAIN"
-	@echo "  docs                           - generate Sphinx HTML documentation with server and live reload using Docker"
-	@echo "  livedocs                       - generate Sphinx HTML documentation with server and live reload"
-	@echo "  build-docs                     - generate Sphinx HTML documentation using Docker"
+	@echo "  docs                           - generate mkdocs HTML documentation with server and live reload using Docker"
+	@echo "  docs-setup                     - install dependencies required for building the docs"
+	@echo "  livedocs                       - generate mkdocs HTML documentation with server and live reload"
+	@echo "  build-docs                     - generate mkdocs HTML documentation using Docker"
 	@echo "  build-ci                       - build docker images for use in our CI pipeline"
 	@echo "  test-ci                        - run tests against files in docker image built by CI"
 	@echo "  compile-requirements           - update Python requirements files using pip-compile"
@@ -131,10 +132,13 @@ docs: .docker-build-pull
 	${DC} up docs
 
 build-docs: .docker-build-pull
-	${DC} run app make -C docs/ clean html
+	${DC} run app make -C docs/ clean build
+
+docs-setup:
+	${MAKE} -C docs/ clean preflight
 
 livedocs:
-	${MAKE} -C docs/ clean livehtml
+	${MAKE} -C docs/ clean serve
 
 test_infra/fixtures/tls.json:
 	${DOCKER} run -it --rm jumanjiman/ssllabs-scan:latest --quiet https://${TEST_DOMAIN}/en-US/ > "test_infra/fixtures/tls.json"
@@ -204,4 +208,4 @@ install-custom-git-hooks:
 uninstall-custom-git-hooks:
 	rm .git/hooks/post-merge
 
-.PHONY: all clean build pull docs livedocs build-docs lint run stop kill run-shell shell test test-image rebuild build-ci test-ci fresh-data djshell run-prod build-prod test-cdn compile-requirements check-requirements install-local-python-deps preflight clean-local-deps install-custom-git-hooks uninstall-custom-git-hooks run-local-task-queue
+.PHONY: all clean build pull docs docs-setup livedocs build-docs lint run stop kill run-shell shell test test-image rebuild build-ci test-ci fresh-data djshell run-prod build-prod test-cdn compile-requirements check-requirements install-local-python-deps preflight clean-local-deps install-custom-git-hooks uninstall-custom-git-hooks run-local-task-queue

docker-compose.yml

@@ -133,7 +133,7 @@ services:
   docs:
     image: mozmeao/bedrock_test:${GIT_COMMIT:-latest}
     platform: linux/amd64
-    command: sphinx-autobuild "docs" "docs/_build/html" --host 0.0.0.0 --port 8100
+    command: mkdocs serve -a "0.0.0.0:8100"
     ports:
       - "8100:8100"
     volumes:

docs/Makefile

@@ -6,7 +6,7 @@
 
 BUILDDIR      = site
 
-.PHONY: help clean preflight serve
+.PHONY: help clean preflight serve build
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -21,4 +21,7 @@ preflight:
 	pip install -r ../requirements/docs.txt
 
 serve:
-	mkdocs serve
+	mkdocs serve --open
+
+build:
+	mkdocs build

docs/docs/install.md

@@ -272,26 +272,23 @@ $ make build-prod run-prod
 
 ### Documentation
 
-This is a great place for coders and non-coders alike to contribute! Please note most of the documentation is currently in [reStructuredText](https://bashtage.github.io/sphinx-material/basics.html) but we also support [Markdown](https://www.markdownguide.org/) files.
+This is a great place for coders and non-coders alike to contribute!
 
 If you see a typo or similarly small change, you can use the "Edit in GitHub" link to propose a fix through GitHub. Note: you will not see your change directly committed to the main branch. You will commit the change to a separate branch so it can be reviewed by a staff member before merging to main.
 
-If you want to make a bigger change or [find a Documentation issue on the repo](https://github.com/mozilla/bedrock/labels/Documentation), it is best to edit and preview locally before submitting a pull request. You can do this with Docker or Local installations. Run the commands from your root folder. They will build documentation and start a live server to auto-update any changes you make to a documentation file.
-
-Docker:
-
-``` bash
-$ make docs
-```
-
-Local:
+If you want to make a bigger change or [find a Documentation issue on the repo](https://github.com/mozilla/bedrock/labels/Documentation), it is best to edit and preview locally before submitting a pull request. Run the commands from your root folder. They will build documentation and start a live server to auto-update any changes you make to a documentation file.
 
+#### Docker
 ``` bash
-$ pip install -r requirements/docs.txt
+make docs
 ```
 
+#### Local
 ``` bash
-$ make livedocs
+# docs-setup installs the docs requirements
+# only need to run this the first time
+make docs-setup
+make livedocs
 ```
 
 ## Localization