book publishing should fail more gracefully when page-building errors are encountered (#39) · Issues · Documentation / Docs Publisher

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 the hooks-op-4 branch of civicrm-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 within pymdown-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 in mkdocs.yml) and then stopped there without attempting to build any pages listed after markdownrules.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 and master versions of the Dev Guide also ended up pointing to this botched branch of hooks-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 loading https://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'