Add tips for writing docs, tweak doc scripts (#1554)

m3db · Apr 19, 2019 · 77e3b0b · 77e3b0b
1 parent 5fba647
commit 77e3b0b
Show file tree

Hide file tree

Showing 7 changed files with 363 additions and 6 deletions.
diff --git a/Makefile b/Makefile
@@ -190,7 +190,7 @@ release-snapshot: check-for-goreleaser-github-token
 .PHONY: docs-container
 docs-container:
 	docker run --rm hello-world >/dev/null
-	docker build -t m3db-docs -f scripts/docs.Dockerfile docs
+	docker build -t m3db-docs docs
 
 # NB(schallert): if updating this target, be sure to update the commands used in
 # the .buildkite/docs_push.sh. We can't share the make targets because our

diff --git a/scripts/docs.Dockerfile → docs/Dockerfile b/scripts/docs.Dockerfile → docs/Dockerfile
@@ -9,6 +9,9 @@ EXPOSE 8000
 
 # mkdocs needs git-fast-import which was stripped from the default git package
 # by default to reduce size
-RUN pip install mkdocs==0.17.3 mkdocs-material==2.7.3 && \
-    apk add --no-cache git-fast-import openssh-client
+RUN pip install \
+    mkdocs==0.17.3 \
+    pymdown-extensions==6.0 \
+    mkdocs-material==2.7.3
+RUN apk add --no-cache git-fast-import openssh-client
 ENTRYPOINT [ "/bin/ash", "-c" ]
diff --git a/docs/misc/writing_docs.md b/docs/misc/writing_docs.md
diff --git a/docs/introduction/components/components.md → docs/overview/components.md b/docs/introduction/components/components.md → docs/overview/components.md
diff --git a/docs/introduction/media/media.md → docs/overview/media.md b/docs/introduction/media/media.md → docs/overview/media.md
diff --git a/docs/introduction/motivation/motivation.md → docs/overview/motivation.md b/docs/introduction/motivation/motivation.md → docs/overview/motivation.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -34,12 +34,30 @@ edit_uri: edit/master/docs/
 repo_name: m3db/m3
 repo_url: https://github.com/m3db/m3
 
+markdown_extensions:
+  - pymdownx.arithmatex
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:pymdownx.emoji.to_svg
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+
 pages:
   - "Introduction": "index.md"
   - "Overview":
-    - "Components": "introduction/components/components.md"
-    - "Motivation": "introduction/motivation/motivation.md"
-    - "Media":      "introduction/media/media.md"
+    - "Components": "overview/components.md"
+    - "Motivation": "overview/motivation.md"
+    - "Media":      "overview/media.md"
   - "M3DB":
     - "Introduction": "m3db/index.md"
     - "Architecture":
@@ -89,3 +107,4 @@ pages:
       - "m3query Performance":  "performance/m3query/index.md"
   - "Troubleshooting": "troubleshooting/index.md"
   - "FAQs": "faqs/index.md"
+  - "Tips For Writing Documentation": "misc/writing_docs.md"