Split User Guide into smaller parts #552
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Codecov Report
@@ Coverage Diff @@
## master #552 +/- ##
==========================================
+ Coverage 95.71% 95.76% +0.05%
==========================================
Files 23 23
Lines 3315 3331 +16
Branches 609 610 +1
==========================================
+ Hits 3173 3190 +17
Misses 69 69
+ Partials 73 72 -1
Flags with carried forward coverage won't be shown. Click here to find out more.
Continue to review full report at Codecov.
|
Spacetown
reviewed
Jan 8, 2022
latk
added a commit
to latk/gcovr
that referenced
this pull request
Jan 22, 2022
latk
added a commit
to latk/gcovr
that referenced
this pull request
Jan 22, 2022
Spacetown
approved these changes
Jan 23, 2022
| 3. Running the program will increment the in-memory coverage counters. | ||
| At the en 8000 d, the counters are written into gcov data files, | ||
| one for each compilation unit. | ||
| Here, we would get ``a.gcda`` and ``b.gcda`` files. |
There was a problem hiding this comment.
Are they always written or only if the code was executed? CTC for example only generates a file if the counters where incremented.
Spacetown
reviewed
Jan 23, 2022
Closed
Now, every output format has its own page for tutorial and reference content.
The individual pages should now be more easily digestible. If one section like Filters contains more content, it doesn't distract from the other sections.
The `--add-tracefiles` option terminology was borrowed from lcov. Lcov refers to its .info files as tracefiles, and indeed these play a similar role as our JSON files. However, gcovr doesn't use the "tracefile" terminology in any other place. So I think it is clearer to talk about "merging coverage data" instead.
The README is the de-facto landing page of the project. It includes a nice list
of supported output formats, along with a link to the command line option.
UNFORTUNATELY, this link uses Sphinx syntax that is not supported by the normal
RST (docutils) renderer. This leads to a really ugly view on GitHub with raw RST
syntax. For example:
* :option:`--html<gcovr --html>`: HTML summaries
SOLUTION: the list is now formatted as a table consisting of RST substitution
references. The table is written in the README file but also included on the
website. Each variant defines these substitutions differently:
* The README version renders the CLI flags as verbatim text without links.
Links to the guides go to the stable version of the website.
* The website version renders the flags and guide links via the expected Sphinx
syntax.
Drawback of this change is that it will take more effort to maintain these
links. It's also less than ideal to link to the stable version, but that seems
to be the best approach when considering that outside users are likely to follow
these links.
Previously, tutorial-level explanation on compiling for coverage was part of the TXT format documentation. Now, it was moved to a separate page.
The root option defaults to the current directory `.` so mentioning it explicitly is unnecessary and distracting. Similarly, explicit --output flags are best avoided.
(and fix some of the other entries that confused me)
and apply slight modernizations, e.g. replacing str.format() with f""-strings.
and migrate string formatting to f""-strings
The "XML" format is a confusing name since it could relate to both the Cobertura and Sonarqube output. This commit adds the --cobertura option as a less confusing alternative. The documentation was updated throughout to nudge the user towards this option. As a side effect, this changes the config file key from `xml` to `cobertura`. This commit does not deprecate the old -x/--xml/--xml-pretty option names, but only because it is not reasonably possible to emit a deprecation message. In contrast, the configuration key had to be renamed since config keys cannot have aliases. The following approaches for generating a deprecation warning with argparse were considered but ultimately discarded: * wrapping the "type" conversion function for the argument. This doesn't work because a "type" function is not supported for some "action" types. * implementing custom "action" types. This would require re-implementing the argparse._StoreAction classes and so on, which is a lot of work for limited gain. While argparse does offer a stable interface for custom actions, this would require further integration/reimplementation of argparse details. * writing a custom argparse replacement. This is not insane since value conversion is already highly customized, and all that argparse provides is associating --option names with their values. However, we cannot get rid of argparse without also rewriting the Sphinx-Autoprogram extension.
latk
added a commit
to latk/gcovr
that referenced
this pull request
Mar 25, 2022
* docs: clarify when coverage counters are updated * docs: mention that symlinks are supported on Windows * configuration: explicitly break exception chaining
|
CI is currently not running due to scheduled maintenance on GH actions, but should resume later today. |
* docs: clarify when coverage counters are updated * docs: mention that symlinks are supported on Windows * configuration: explicitly break exception chaining
latk
added a commit
that referenced
this pull request
Mar 25, 2022
D-Walther
pushed a commit
to D-Walther/gcovr
that referenced
this pull request
Jun 16, 2025
D-Walther
pushed a commit
to D-Walther/gcovr
that referenced
this pull request
Jun 16, 2025
* docs: clarify when coverage counters are updated * docs: mention that symlinks are supported on Windows * configuration: explicitly break exception chaining
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The user guide was getting extremely long and unwieldy. This pull request proposes to split it up into separate pages. For example, every output format now has its own page.
Downsides: more complicated URL structure, breaks existing links into the documentation.
This also helped to separate some concerns that had become mixed. Originally, the user guide started with a quickstart guide. Then, more and more output formats came along. The result was that the documentation for the txt output (the oldest format) also served as a tutorial for using gcovr. Now, those more tutorial-style parts have been moved to separate pages.
Other changes:
-rand-ooptions – they are usually unnecessaryThe pull request is split into multiple commits that can be reviewed one at a time.