[docs] Re-implement build process using Sphinx

[jugglinmike]

Prior to this commit, WPT used the Jekyll static site generator [1] to
create a website from the project documentation. Jekyll has some
restrictions which limit the utility of the generated website. Sphinx
[2] has a number of features which will enable future improvements to
the documentation

• it can including content from files located outside of the designated
  "documentation" directory (some maintainers prefer to organize content
  elsewhere [3])
• it can generate documentation for Python CLIs like wptrunner [4]
• the website it produces has a fully-featured client-side search
  interface
• it can generating documentation for arbitrary Python files (the WPT
  documentation occasionally falls out of sync with the project's custom
  linter)
• it detects and reports broken links and orphaned content (the WPT
  documentation has suffered from both problems in the past [5] [6] [7])
• as a Python tool, it presents less friction for local development than
  the Ruby-based Jekyll

Although Sphinx parses content in the reStructured Text format by
default, the existing content in WPT is formatted in Markdown. Markdown
is generally preferable for this purpose because it is more familiar to
the potential contributors to WPT and because the maintainers have no
immediate plans to output to a format that is not a website. In
recognition of this, enable the project's support for CommonMark.

[1] https://jekyllrb.com/
[2] https://www.sphinx-doc.org
[3] web-platform-tests/wpt#5289
[4] https://github.com/ribozz/sphinx-argparse
[5] web-platform-tests/wpt#5299
[6] web-platform-tests/wpt#10501
[7] web-platform-tests/wpt#11479

[zcorpan]

What are the steps to build docs locally?

I did this

$ cd docs
$ pip install -U Sphinx
$ make html
Running Sphinx v1.8.5

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/usr/local/lib/python2.7/site-packages/sphinx/config.py", line 368, in eval_config_file
    execfile_(filename, namespace)
  File "/usr/local/lib/python2.7/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/usr/local/lib/python2.7/site-packages/six.py", line 709, in exec_
    exec("""exec _code_ in _globs_, _locs_""")
  File "<string>", line 1, in <module>
  File "/Users/zcorpan/git/web-platform-tests/wpt/docs/conf.py", line 77, in <module>
    from recommonmark.transform import AutoStructify
ImportError: No module named recommonmark.transform

make: *** [html] Error 2

[jugglinmike]

ImportError: No module named recommonmark.transform

This means the recommonmark module is not available. You can install it with pip install recommonmark, and you can tell me to add a requirements.txt file to this patch.

[zcorpan]

@jugglinmike , please add a requirements.txt file to this patch.

Also instructions in README or so would be nice. :)

[jugglinmike]

@jugglinmike , please add a requirements.txt file to this patch.

Also instructions in README or so would be nice. :)

Done and done.

[jugglinmike]

I merged this to verify that it would function as expected on system provided by readthedocs.org. The good news is that it does. The bad news is that I can't re-open a merged pull request. I've reset the changes on the target branch and created a new pull request to continue the review: gh-11.

Sorry for the noise!