ci(docs): Make CI job build_doc fail if a warning occurs¶
Description¶
Abstract¶
Add a new make command, doc-strict, that will fail if a warning is generated during the build, and use this command in the build_doc CI job
Motivation¶
As seen in the two previous commits, we weren’t able to see two failures during the build of the documentation: - badly formatted README file - error when running git_to_sphinx
It was only visible when looking at the documentation.
Rationale¶
sphinx-build accepts a -W argument that treats warnings as errors.
It’s not possible to use it with the make commands of the docs MakeFile, so we had to put the whole sphinx-build command in the make doc-strict command.
Info¶
- Hash
3ea3c14f0befb167c3438835e58c3238972b42c1
- Date
2019-08-16 00:16:52 +0200
- Parents
docs(fix): Fix usage of `pydriller` in `git_to_sphinx` [200d022d] — 2019-08-16 00:12:17 +0200
- Children
Merge branch ‘feature/twidi/fix-commits-in-doc’ into develop [841496f6] — 2019-08-16 00:22:32 +0200
- Branches
- Tags
(No tags)
Changes¶
.circleci/config.yml¶
- Type
Modified
- Stats
+1 -1
@@ -152,7 +152,7 @@ jobs:
name: Build documentation
command: |
source ~/venv/bin/activate
- make doc
+ make doc-strict
# run check and tests for every commit in the history for which it is not already done
check_every_commit:
Makefile¶
- Type
Modified
- Stats
+6 -0
@@ -54,6 +54,12 @@ doc: clean-doc ## Build the documentation
@echo "$(BOLD)Building documentation$(RESET)"
@cd docs && $(MAKE) html
+.PHONY: doc-strict docs-strict
+docs-strict: doc-strict # we allow "doc-strict" and "docs-strict"
+doc-strict: clean-doc ## Build the documentation but fail if a warning
+ @echo "$(BOLD)Building documentation (strict)$(RESET)"
+ @cd docs && sphinx-build -W -b html . _build
+
.PHONY: clean-docs
clean-docs: clean-doc # we allow "clean-doc" and "clean-docs"
clean-doc: ## Clean the documentation directories