Update mkdocs

[carltongibson]

We're on an old version of MKDocs mkdocs==0.16.3.

This isn't compatible with Python 3:

  File "/home/travis/build/encode/django-rest-framework/.tox/venvs/docs/lib/python3.7/site-packages/mkdocs/config/base.py", line 105, in validate
    post_failed, post_warnings = self._post_validate()
  File "/home/travis/build/encode/django-rest-framework/.tox/venvs/docs/lib/python3.7/site-packages/mkdocs/config/base.py", line 85, in _post_validate
    config_option.post_validation(self, key_name=key)
  File "/home/travis/build/encode/django-rest-framework/.tox/venvs/docs/lib/python3.7/site-packages/mkdocs/config/config_options.py", line 391, in post_validation
    for filename in self.walk_docs_dir(config['docs_dir']):
RuntimeError: generator raised StopIteration

So the docs build (from #6615):

[testenv:docs]
basepython = python2.7
skip_install = true
commands = mkdocs build
deps =
       -rrequirements/requirements-testing.txt
       -rrequirements/requirements-documentation.txt

Building with latest Mkdocs, it looks like the theme isn't compatible...

INFO    -  Building documentation... 
WARNING -  Config value: 'theme_dir'. Warning: Unrecognised configuration name: theme_dir 
WARNING -  Config value: 'pages'. Warning: The 'pages' configuration option has been deprecated and will be removed in a future release of MkDocs. Use 'nav' instead. 
INFO    -  Cleaning site directory 
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
  - topics/writable-nested-serializers.md 
WARNING -  Documentation file 'index.md' contains a link to '.' which is not found in the documentation files. 

What do we need to do to update?

@tomchristie @xordoquy: this is from the dawn-of-time; do either of you recall what the story is here?

[tomchristie]

"We're on an old version of MKDocs mkdocs==0.16.3. This isn't compatible with Python 3"

😢 Oh noes.

You'd need to dig in the MkDocs 0.17 release notes to figure out what needs to change. https://www.mkdocs.org/about/release-notes/#version-0170-2017-10-19

Eg. theme_dir is no longer valid - needs to be along these lines instead...

theme:
    name: mkdocs
    custom_dir: custom

There'll be some bits of our theme templates that're likely incompatible too - but I'd suggest starting by trying to upgrade to 0.17.0 and seeing what's broken at that point.

[rpkilby]

One issue in upgrading to 0.17.x and above is mkdocs/mkdocs#1471