move to mkdocs

.circleci/config.yml

@@ -46,7 +46,6 @@ jobs:
       - setup_remote_docker
       - run: make
       - run: make lint
-      - run: make test-docs
       - run:
           name: Check that generated files haven't been changed since checkout
           command: |

.github/workflows/check-links.yaml

@@ -0,0 +1,28 @@
+# https://github.com/marketplace/actions/link-checker
+on: [push, pull_request]
+name: Check links in docs
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.8]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v1
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+      - name: Build docs for link check
+        run: mkdocs build
+      - name: Link Checker
+        id: lc
+        uses: peter-evans/link-checker@v1
+        with:
+          args: -r -d site/ -v site/index.html
+      - name: Fail if there were link errors
+        run: exit ${{ steps.lc.outputs.exit_code }}

.gitignore

@@ -29,4 +29,4 @@ terraform.tfstate.backup
 tf.json
 
 # Docs
-docs/_build
+site

.readthedocs.yaml

@@ -5,13 +5,9 @@
 # Required
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
-
 # Build documentation with MkDocs
-#mkdocs:
-#  configuration: mkdocs.yml
+mkdocs:
+  configuration: mkdocs.yml
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to the project
 
-Our doc on [developing `wksctl`](https://wksctl.readthedocs.io/en/latest/development.html) will be helpful when getting started contributing as well.
+Our doc on [developing `wksctl`](https://wksctl.readthedocs.io/en/latest/development) will be helpful when getting started contributing as well.
 
 ## Typical workflow
 

Makefile

@@ -9,8 +9,6 @@ GIT_REVISION := $(shell git rev-parse HEAD)
 VERSION=$(shell git describe --always)
 UPTODATE := .uptodate
 
-DOCS_PORT:=8000
-
 # Every directory with a Dockerfile in it builds an image called
 # $(IMAGE_PREFIX)<dirname>. Dependencies (i.e. things that go in the image)
 # still need to be explicitly declared.
@@ -147,12 +145,8 @@ integration-tests-container: cmd/wksctl/wksctl cmd/controller/.uptodate
 FORCE:
 
 
-build-docs:
-	@cd docs && docker build -t wksctl-docs .
-
-test-docs: build-docs
-	@docker run -it wksctl-docs /usr/bin/linkchecker _build/html/index.html
+docs-deps:
+	pip3 install -r docs/requirements.txt
 
-serve-docs: build-docs
-	@echo Stating docs website on http://localhost:${DOCS_PORT}/_build/html/index.html
-	@docker run -i -p ${DOCS_PORT}:8000 -e USER_ID=$$UID wksctl-docs
+serve-docs: docs-deps
+	mkdocs serve

README.md

@@ -23,16 +23,16 @@ chmod +x wksctl
 sudo mv wksctl /usr/local/bin/
 ```
 
-Check out [our Get Started doc](https://wksctl.readthedocs.io/en/latest/get-started.html) to dive deeper into the different ways to operate `wksctl`.
+Check out [our Get Started doc](https://wksctl.readthedocs.io/en/latest/get-started) to dive deeper into the different ways to operate `wksctl`.
 
 ## Quick start
 
 We put together a couple of guides to get you up and running with WKS in combination with [Footloose](https://github.com/weaveworks/footloose), [Vagrant](https://www.vagrantup.com) and others!
 
 - [Firekube](https://github.com/weaveworks/wks-quickstart-firekube) - use our WKS + Footloose + Ignite demo and be up and running in no time
-- [WKS and Footloose](https://wksctl.readthedocs.io/en/latest/wks-and-footloose.html)
-- [WKS and Vagrant](https://wksctl.readthedocs.io/en/latest/wks-and-vagrant.html)
-- [WKS on GCE](https://wksctl.readthedocs.io/en/latest/wks-on-gce.html)
+- [WKS and Footloose](https://wksctl.readthedocs.io/en/latest/wks-and-footloose)
+- [WKS and Vagrant](https://wksctl.readthedocs.io/en/latest/wks-and-vagrant)
+- [WKS on GCE](https://wksctl.readthedocs.io/en/latest/wks-on-gce)
 
 ## Contributing
 
@@ -41,12 +41,12 @@ Please see [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code Of Conduct](CODE_OF_
 Other interesting resources include:
 
 - [The issue tracker](https://github.com/weaveworks/wksctl/issues)
-- [Developing `wksctl`](https://wksctl.readthedocs.io/en/latest/development.html)
+- [Developing `wksctl`](https://wksctl.readthedocs.io/en/latest/development)
 
 ## More Documentation
 
-- [Frequently asked questions](https://wksctl.readthedocs.io/en/latest/faq.html)
-- [Developing `wksctl`](https://wksctl.readthedocs.io/en/latest/development.html)
+- [Frequently asked questions](https://wksctl.readthedocs.io/en/latest/faq)
+- [Developing `wksctl`](https://wksctl.readthedocs.io/en/latest/development)
 
 ## Getting Help
 

docs/_static/custom.css

@@ -1,15 +1,24 @@
 @import url("https://fonts.googleapis.com/css?family=Montserrat&display=swap");
-@import url("https://fonts.googleapis.com/css?family=Roboto+Mono&display=swap");
 
 body {
   font-family: "Montserrat", sans-serif;
 }
 
-.rst-content pre.literal-block, .rst-content div[class^="highlight"] pre, .rst-content .linenodiv pre {
-  font-family: "Roboto Mono", monospace;
+.md-logo {
+    width: 40px;
+    height: 40px;
+    padding-bottom: 2px;
+    padding-top: 2px;
+}
+.md-logo img {
+    width: 40px;
+    height: 40px;
 }
 
-code {
-  font-family: "Roboto Mono", monospace;
+.md-header, .md-footer-nav {
+    background-image: linear-gradient(45deg, rgb(0, 150, 225) 0%, rgb(27, 141, 226) 24%, rgb(42, 125, 227) 53%, rgb(53, 112, 227) 78%, rgb(53, 112, 227) 100%);
 }
 
+.md-header-nav__title {
+    font-size: .85rem;
+}

docs/development.md

@@ -42,9 +42,5 @@ and we use Markdown for everything. Every new commit will be published at
 
 A few things to be aware of:
 
-- The landing page (`docs/index.rst`) is written in reStructuredText, because readthedocs uses sphinx for generating HTML/PDF/etc. Make sure your new doc is listed there - it's how the index is built. (`recommonmark` is used as the bridge between Markdown and reStructuredText).
-- Use `make serve-docs` to generate the docs locally and point a webbrowser to the URL in the output, e.g. `localhost:8000/_build/html`, to check out if your changes worked out.
-- Links in the docs will be automatically tested.
-- Gotcha 1: links in markdown tables are problematic: <https://github.com/ryanfox/sphinx-markdown-tables/issues/18>
-- Gotcha 2: cross-referencing using anchors is problematic: <https://github.com/readthedocs/recommonmark/issues/8>
-- Gotcha 3: Make sure your use of headings, e.g. `#`, `##`, `###` makes sense. The table of contents will be a bit upset if you don't.
+- Use `make serve-docs` to serve the docs locally and point a webbrowser to the URL in the output, e.g. `localhost:8000`, to check out if your changes worked out.
+- Upon pushing a PR to this repository, links in the docs will be automatically tested.

docs/get-started.md

@@ -1,4 +1,4 @@
-# Get started with `wksctl`
+# Get started with wksctl
 
 Using `wksctl` you have two modes of operation. **Standalone** mode and **GitOps** mode. The latter will enable you to keep the state of the cluster itself in Git too.