book publishing should fail more gracefully when page-building errors are encountered
Created by: seanmadsen
On 2017-02-04 we had a little snafu with the Dev Guide. Here's what happened, chronologically:
- On 2017-02-03 Michael (at my request) took these steps to install a more bleeding edge version of
pymdown-extensions
in attempt at addressing civicrm-docs-material#7 - Shortly thereafter, I made 3 commits, tested them locally with success (with the same version of
pymdown-extensions
), and then pushed them to thehooks-op-4
branch ofcivicrm-dev-docs
. - After this push, the docs system attempted to publish the
hooks-op-4
branch but encountered an error that I am fairly certain stemmed from a bug withinpymdown-extensions
and caused by the more bleeding edge version. Unfortunately I have not been able to reproduce this bug locally🙁 - The full error output is below
- Most notably:
ERROR - Error building page markdownrules.md
- Unfortunately MkDocs didn't handle this error gracefully because it built all the pages up to
markdownrules.md
(as listed inmkdocs.yml
) and then stopped there without attempting to build any pages listed aftermarkdownrules.md
. (That's too bad, but seems like an upstream issue with MkDocs that we probably can't control so easily.)- (Issue A): What would be good, is if civicrm-docs could attempt to build a book, and then only make it live if the build process completes succesfully.
- The especially bad (and strange) thing that happened here is that somehow the
latest
andmaster
versions of the Dev Guide also ended up pointing to this botched branch ofhooks-op-4
.- (Issue B): The errors in publishing one branch ended up messing up another branch. I imagine we should be able to prevent this somehow.
- Then on 2017-02-04 @ErichBSchulz pointed out the problem with the master branch, and I tried to re-publish that branch (without publishing
hooks-op-4
) by loadinghttps://docs.civicrm.org/admin/publish/dev/en/master
- (Issue C): publishing the master branch with the URL above didn't work during this time when the Dev Guide was "messed up". I forget the exact error I got when I tried. Either 404 or 500 or 503.
- Then I asked @bgm to do the following on the server, and these steps got the
master
branch up and running again:cd /path/to/civicrm-docs/site ./bin/console docs:publish dev/en/master
Again a can't reproduce any of this locally, so I'm not sure how best to proceed here. Hoping that @michaelmcandrew will think of something.
Full error given by the publishing system
(This was emailed to me)
Running 'mkdocs build -c -f /var/www/civicrm-docs/var/repos/buildfiles/dev.en.master.yml -d /var/www/civicrm-docs/app/../web/static/dev/en/master'
INFO: mkdocs output: '
INFO - Cleaning site directory
INFO - Building documentation to directory: /var/www/civicrm-docs/web/static/dev/en/master
ERROR - Error building page markdownrules.md Traceback (most recent call last):
File "/usr/local/bin/mkdocs", line 11, in sys.exit(cli())
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 722, in __call__ return self.main(*args, **kwargs)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 697, in main rv = self.invoke(ctx)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 1066, in invoke return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 895, in invoke return ctx.invoke(self.callback, **ctx.params)
File "/usr/local/lib/python2.7/dist-packages/click/core.py", line 535, in invoke return callback(*args, **kwargs)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/__main__.py", line 156, in build_command ), dirty=not clean)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 379, in build build_pages(config, dirty=dirty)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 332, in build_pages dump_json)
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 188, in _build_page site_navigation=site_navigation
File "/usr/local/lib/python2.7/dist-packages/mkdocs/commands/build.py", line 59, in convert_markdown extension_configs=config['mdx_configs']
File "/usr/local/lib/python2.7/dist-packages/mkdocs/utils/__init__.py", line 366, in convert_markdown html_content = md.convert(markdown_source)
File "/usr/local/lib/python2.7/dist-packages/markdown/__init__.py", line 368, in convert self.lines = prep.run(self.lines)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 484, in run lines = self.search_nested(lines)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 385, in search_nested self.eval(m, start, end)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 281, in eval self.process_nested_block(m, start, end)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 320, in process_nested_block code = entry["formatter"](self.rebuild_block(self.code), self.lang)
File "/usr/local/lib/python2.7/dist-packages/pymdown_extensions-1.8-py2.7.egg/pymdownx/superfences.py", line 423, in highlight lexer = guess_lexer(self.src) AttributeError: 'SuperFencesBlockPreprocessor' object has no attribute 'src'