Merge html-rewrite

The HTML output was completely overhauled and now features more modern
HTML that should be easier to extend. Importantly, CSS no longer has to
be inline!

This represents roughly six months of "work". Thank you for @opikalo
(#367) for dragging it over the finish line :)

.editorconfig

@@ -0,0 +1,16 @@
+# see https://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+# end_of_line = not relevant because managed by Git
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+# for the web templates, use more compact indent
+[gcovr/templates/*]
+indent_size = 2

.travis.yml

@@ -31,7 +31,7 @@ install:
 
 script:
 - test -z "$RUN_LINTER" || make lint
-- test -z "$RUN_LINTER" || admin/release_checklist --no-verify-tags 4.2
+- test -z "$RUN_LINTER" || admin/release_checklist --no-verify-tags --no-verify-docs-next-version 4.2
 - make test TEST_OPTS="$COVERAGE_OPTS"
 - test -z "$COVERAGE_OPTS" || codecov -X gcov search
 - test -z "$BUILD_DOCS" || make doc

CONTRIBUTING.rst

@@ -3,13 +3,15 @@ Contributing
 
 This document contains:
 
--   our `guidelines for bug reports <How to report bugs_>`_
--   `general contribution guidelines <How to help_>`_
--   a `checklist for pull requests <How to submit a Pull Request_>`_
+-   our :ref:`guidelines for bug reports <report bugs>`
+-   :ref:`general contribution guidelines <help out>`
+-   a :ref:`checklist for pull requests <pull request>`
 -   a developer guide that explains the
-    `development environment <How to set up a development environment_>`_,
-    `project structure <Project Structure_>`_,
-    and `test suite <Test suite_>`_
+    :ref:`development environment <development environment>`,
+    :ref:`project structure <project structure>`,
+    and :ref:`test suite <test suite>`
+
+.. _report bugs:
 
 How to report bugs
 ------------------
@@ -30,6 +32,8 @@ and the smallest possible source file to reproduce the problem.
 
 .. _search all issues: https://github.com/gcovr/gcovr/issues?q=is%3Aissue
 
+.. _help out:
+
 How to help
 -----------
 
@@ -51,6 +55,8 @@ There are many ways how you can help:
 .. _label needs review: https://github.com/gcovr/gcovr/labels/needs%20review
 .. _pull requests: https://github.com/gcovr/gcovr/pulls
 
+.. _pull request:
+
 How to submit a Pull Request
 ----------------------------
 
@@ -122,6 +128,8 @@ If you need assistance for your pull request, you can
   - open an unfinished pull request as a work in progress (WIP),
     and explain what you've like to get reviewed
 
+.. _development environment:
+
 How to set up a development environment
 ---------------------------------------
 
@@ -170,13 +178,15 @@ On **Windows**, you will need to install a GCC toolchain
 as the tests expect a Unix-like environment.
 You can use MinGW-W64 or MinGW.
 To run the tests,
-please make sure that the ``make`` and ``cmake`` from your MinGW distribution 
+please make sure that the ``make`` and ``cmake`` from your MinGW distribution
 are in the system ``PATH``.
 
 If setting up a local toolchain is too complicated,
 you can also run the tests in a Docker container
 (see :ref:`test suite`).
 
+.. _project structure:
+
 Project Structure
 -----------------
 
@@ -224,13 +234,55 @@ and a comprehensive corpus of example projects
 that are executed as the ``test_gcovr.py`` integration test.
 Each ``gcovr/tests/*`` directory is one such example project.
 
+The next sections discuss
+the :ref:`structure of integration tests <integration tests>`,
+how to :ref:`run and filter tests <run tests>`,
+and how to :ref:`run tests with Docker <docker tests>`.
+
+.. _integration tests:
+
+Structure of integration tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Each project in the corpus
-contains a ``Makefile`` and a ``reference`` directory.
+contains a ``Makefile`` and a ``reference`` directory::
+
+   gcovr/tests/sometest/
+     reference/
+     Makefile
+     README
+     example.cpp
+
 The Makefile controls how the project is built,
 and how gcovr should be invoked.
 The reference directory contains baseline files against
 which the gcovr output is compared.
-Each project is once per output format (txt, html, xml, json, sonarqube, ...).
+Tests can be executed even without baseline files.
+
+Each Makefile contains the following targets:
+
+* ``all:`` builds the example project. Can be shared between gcovr invocations.
+* ``run:`` lists available targets
+  which must be a subset of the available output formats.
+* ``clean:`` remove any generated files
+  after all tests of the scenario have finished.
+* output formats (txt, html, json, sonarqube, ...):
+  invoke gcovr to produce output files of the correct format.
+  The test runner automatically finds the generated files (if any)
+  and compares them to the baseline files in the reference directory.
+  All formats are optional,
+  but using at least JSON is recommended.
+* ``clean-each:`` if provided, will be invoked by the test runner
+  after testing each format.
+
+.. _run tests:
+
+Run and filter tests
+~~~~~~~~~~~~~~~~~~~~
+
+To run all tests, use ``make test`` or ``make qa``.
+The tests currently assume that you are using GCC 5
+and have set up a :ref:`development environment <development environment>`.
 
 Because the tests are a bit slow, you can limit the tests to a specific
 test file, example project, or output format.
@@ -253,7 +305,10 @@ For example:
 To see all tests, run pytest in ``-v`` verbose mode.
 To see which tests would be run, add the ``--collect-only`` option.
 
-The tests currently assume that you are using GCC 5.
+.. _docker tests:
+
+Run tests with Docker
+~~~~~~~~~~~~~~~~~~~~~
 
 If you can't set up a toolchain locally, you can run the QA process via Docker.
 First, build the container image:
@@ -276,11 +331,12 @@ Then, run the container, which executes ``make qa`` within the container:
 
     docker run --rm -v `pwd`:/gcovr gcovr-qa
 
+.. _join:
 
 Become a gcovr developer
 ------------------------
 
-After you've contributed a bit 
+After you've contributed a bit
 (whether with discussions, documentation, or code),
 consider becoming a gcovr developer.
 As a developer, you can:

Makefile

@@ -1,7 +1,14 @@
-PYTHON ?= python3
-CC ?= gcc-5
-CXX ?= g++-5
-GCOV ?= gcov-5
+# This Makefile helps perform some developer tasks, like linting or testing.
+# Run `make` or `make help` to see a list of tasks.
+
+# Set a variable if it's empty or provided by `make`.
+# usage: $(call set_sensible_default, NAME, value)
+set_sensible_default = $(if $(filter undefined default,$(origin $(1))),$(2),$(value $(1)))
+
+PYTHON := $(call set_sensible_default,PYTHON,python3)
+CC := $(call set_sensible_default,CC,gcc-5)
+CXX := $(call set_sensible_default,CXX,g++-5)
+GCOV := $(call set_sensible_default,GCOV,gcov-5)
 QA_CONTAINER ?= gcovr-qa
 TEST_OPTS ?=
 

admin/release_checklist

@@ -9,15 +9,25 @@ printerr() {
 }
 
 verify_tags=yes
+verify_docs_next_version=yes
 target_version=
-usage="usage: $0 [--no-verify-tags] TARGET_REVISION"
+usage="usage: $0 [OPTIONS] TARGET_REVISION
+
+Options:
+  --no-verify-tags
+  --no-verify-docs-next-version
+"
 
 while [[ "$#" -gt 0 ]]; do
     case "$1" in
         --no-verify-tags)
             verify_tags=no
             shift
             ;;
+        --no-verify-docs-next-version)
+            verify_docs_next_version=no
+            shift
+            ;;
         -*)
             printerr "unknown argument $1"
             printerr "$usage"
@@ -38,9 +48,20 @@ fi
 
 ok=yes
 
+maybe_error() {
+    local iserr="$1"
+    shift
+    if [[ "$iserr" = yes ]]; then
+        ok=no
+        printerr "ERROR:" "$@"
+    else
+        # ok stays unchanged
+        printerr "WARNING:" "$@"
+    fi
+}
+
 error() {
-    ok=no
-    printerr "ERROR:" "$@"
+    maybe_error yes "$@"
 }
 
 if ! [[ -d .git ]]; then
@@ -58,20 +79,28 @@ grep -qE "version=['\"]gcovr $target_version['\"]" doc/examples/example_xml.xml
     || error "examples: Please regenerate: " \
              "cd doc/examples; ./example_xml.sh > example_xml.xml"
 
-grep -qE "^- .*$0 --no-verify-tags $target_version\$" .travis.yml \
+grep -qE "^- .*$0 --no-verify-tags --no-verify-docs-next-version $target_version\$" .travis.yml \
     || error ".travis.yml: Please update the $0 version"
 
-if [[ "$verify_tags" = yes ]]; then
-    if git tag | grep -qE "^$target_version\$"; then
-        # grandfathering of non-annotated 3.4 tag
-        [[ "$target_version" = 3.4 ]] \
-            || [[ "$(git cat-file -t "$target_version")" = tag ]] \
-            || error "Please use annotated tags (git tag -a) for releases"
-    else
-        error "Please tag this release: git tag -a $target_version"
-    fi
+occurrences="$(
+  grep -E '\.\. (versionadded|versionchanged|deprecated):: NEXT' \
+       -A 1 doc/source/*.rst)"
+test -z "$occurrences" || {
+    maybe_error $verify_docs_next_version \
+                "doc/source/*.rst: please update notes with next version"
+    # shellcheck disable=SC2001
+    echo "$occurrences" | sed 's/^/INFO: /' >&2
+}
+
+if git tag | grep -qE "^$target_version\$"; then
+    # grandfathering of non-annotated 3.4 tag
+    [[ "$target_version" = 3.4 ]] \
+        || [[ "$(git cat-file -t "$target_version")" = tag ]] \
+        || maybe_error $verify_tags \
+                       "Please use annotated tags (git tag -a) for releases"
 else
-    printerr "SKIPPING: tag validation"
+    maybe_error $verify_tags \
+                "Please tag this release: git tag -a $target_version"
 fi
 
 if [[ "$ok" = yes ]]; then

doc/.gitignore

@@ -1,3 +1,4 @@
 examples/gcovr.out
 examples/example-*.html
+examples/example-*.css
 build/*

doc/source/guide.rst

@@ -213,12 +213,28 @@ This generates the following HTML page for the file ``example1.cpp``:
 .. image:: ../images/screenshot-html-details.example.cpp.png
     :align: center
 
-Note that the ``--html-details`` option can only be used with the
-``-o`` (``--output``) option.  For example, if the ``--output`` option
-specifies the output file ``coverage.html``, then the web pages
-generated for each file will have names of the form
+Note that the ``--html-details`` option needs a named output,
+e.g. via the the ``-o`` (``--output``) option.
+For example, if the output is named ``coverage.html``,
+then the web pages generated for each file will have names of the form
 ``coverage.<filename>.html``.
 
+The ``--html-self-contained`` option controls whether assets like CSS styles
+are bundled into the HTML file.
+The ``--html`` report defaults to self-contained mode.
+but ``--html-details`` defaults to ``--no-html-self-contained``
+in order to avoid problems with the `Content Security Policy <CSP_>`_
+of some servers, especially Jenkins.
+
+.. _CSP: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
+
+.. versionadded:: NEXT
+   Added ``--html-self-contained`` and ``--no-html-self-contained``.
+
+.. versionchanged:: NEXT
+   Default to external CSS file for ``--html-details``.
+
+
 .. _sonarqube_xml_output:
 
 Sonarqube XML Output