1489407 - Docs build failing with "ImportError: No module named CommonMark"

Status: RESOLVED FIXED

(Tree Management :: Treeherder, defect, P1)

Description

[Ed Morley [:emorley]]

The docs build is perma-failing with:
https://readthedocs.org/projects/treeherder/builds/7749843/

```
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/treeherder/envs/latest/local/lib/python2.7/site-packages/sphinx/config.py", line 161, in __init__
    execfile_(filename, config)
  File "/home/docs/checkouts/readthedocs.org/user_builds/treeherder/envs/latest/local/lib/python2.7/site-packages/sphinx/util/pycompat.py", line 150, in execfile_
    exec_(code, _globals)
  File "/home/docs/checkouts/readthedocs.org/user_builds/treeherder/envs/latest/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 "conf.py", line 2, in <module>
    from recommonmark.parser import CommonMarkParser
  File "/home/docs/checkouts/readthedocs.org/user_builds/treeherder/envs/latest/src/recommonmark/recommonmark/parser.py", line 9, in <module>
    from CommonMark import Parser
ImportError: No module named CommonMark
```

This appears to be due to an upstream breaking change in minor version:
https://github.com/rtfd/CommonMark-py/issues/134
https://github.com/rtfd/recommonmark/issues/114

Comment 1

[GitHub Bugzilla PR Linker]

Attachment: Link to GitHub pull-request: https://github.com/mozilla/treeherder/pull/3998

Comment 2

[Treeherder GitHub Bugbot]

Commit pushed to master at https://github.com/mozilla/treeherder

https://github.com/mozilla/treeherder/commit/817ac227f3cd6b2dfeb049f853b68269552a2964
Bug 1489407 - Docs: Pin to older version of CommonMark to fix build (#3998)

CommonMark has made a breaking package change in a minor version
release (0.8.0), so we need to pin to the last working release. See:
https://github.com/rtfd/CommonMark-py/issues/134

Fixes:

```
  ...
  File ".../recommonmark/recommonmark/parser.py", line 9, in <module>
    from CommonMark import Parser
ImportError: No module named CommonMark
```

The Travis docs setup step has also been modified to always upgrade
dependencies, which will mean we will catch cases like this on Travis
next time.

Comment 3

[Ed Morley [:emorley]]

Since the docs builds were failing I've just gone ahead and merged this.

Longer term I think we should ditch sphinx/commonmark and use mkdocs/python-markdown (and ideally also the material theme, though Read The Docs blocks custom themes, so we'll need to switch hosting too). These changes are bug 1466084.

Comment 4

[Ed Morley [:emorley]]

The latest build succeeded:
https://readthedocs.org/projects/treeherder/builds/7750405/