From b77bb690e260a84879b7980c58d858244f556d31 Mon Sep 17 00:00:00 2001 From: boxydog Date: Sat, 1 Jun 2024 18:13:05 -0500 Subject: [PATCH 1/3] Improve test coverage, docs, and .gitignore --- .coveragerc | 4 +- .gitignore | 6 +++ docs/contribute.rst | 28 ++++++++++++++ .../article_with_md_extension.md | 1 + pelican/tests/test_pelican.py | 37 ++++++++++++++++++- 5 files changed, 73 insertions(+), 3 deletions(-) create mode 120000 pelican/tests/simple_content/article_with_md_extension.md diff --git a/.coveragerc b/.coveragerc index fdd2cad6..6347d80b 100644 --- a/.coveragerc +++ b/.coveragerc @@ -1,2 +1,4 @@ [report] -omit = pelican/tests/* +omit = + pelican/tests/* + pelican/signals.py diff --git a/.gitignore b/.gitignore index 473efea2..65e4d759 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,9 @@ samples/output *.lock .pdm-python .venv + +# direnv +.envrc + +# pycharm +.idea diff --git a/docs/contribute.rst b/docs/contribute.rst index 6a5a417e..419ba80f 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -64,6 +64,20 @@ your bug fix or feature:: Now you can make changes to Pelican, its documentation, and/or other aspects of the project. +Setting up git blame +-------------------- + +``git blame`` annotates lines from a file with information about the pull request +that last modified it. Sweeping shallow changes (like formatting) can make that +information less useful, so we keep a list of such changes to be ignored. To set +that up in your repository:: + + git config blame.ignoreRevsFile .git-blame-ignore-revs + +For more information, see here_. + +.. _here: https://www.michaelheap.com/git-ignore-rev/ + Running the test suite ---------------------- @@ -108,6 +122,20 @@ environments. .. _Tox: https://tox.readthedocs.io/en/latest/ +Running a code coverage report +------------------------------ + +The code is more likely to stay robust if it is tested. +coverage_ is a library that measures how much of the code is tested. +To run it:: + + invoke coverage + open htmlcov/index.html + +The HTML will show overall coverage, coverage per file, and even line-by-line coverage. + +.. _coverage: https://github.com/nedbat/coveragepy + Building the docs ----------------- diff --git a/pelican/tests/simple_content/article_with_md_extension.md b/pelican/tests/simple_content/article_with_md_extension.md new file mode 120000 index 00000000..00a11ad3 --- /dev/null +++ b/pelican/tests/simple_content/article_with_md_extension.md @@ -0,0 +1 @@ +../content/article_with_md_extension.md \ No newline at end of file diff --git a/pelican/tests/test_pelican.py b/pelican/tests/test_pelican.py index 075f55eb..2bea1e4e 100644 --- a/pelican/tests/test_pelican.py +++ b/pelican/tests/test_pelican.py @@ -1,3 +1,5 @@ +import contextlib +import io import locale import logging import os @@ -6,9 +8,12 @@ import sys import unittest from collections.abc import Sequence from shutil import rmtree -from tempfile import mkdtemp +from tempfile import TemporaryDirectory, mkdtemp +from unittest.mock import patch -from pelican import Pelican +from rich.console import Console + +from pelican import Pelican, __version__, main from pelican.generators import StaticGenerator from pelican.settings import read_settings from pelican.tests.support import ( @@ -271,3 +276,31 @@ class TestPelican(LoggedTestCase): [sys.executable, "-m", "pelican", "--help"] ).decode("ascii", "replace") assert "usage:" in output + + def test_main_version(self): + """Run main --version.""" + out = io.StringIO() + with contextlib.redirect_stdout(out): + with self.assertRaises(SystemExit): + main(["--version"]) + self.assertEqual(f"{__version__}\n", out.getvalue()) + + def test_main_help(self): + """Run main --help.""" + out = io.StringIO() + with contextlib.redirect_stdout(out): + with self.assertRaises(SystemExit): + main(["--help"]) + self.assertIn("A tool to generate a static blog", out.getvalue()) + + def test_main_on_content(self): + """Invoke main on simple_content directory.""" + out, err = io.StringIO(), io.StringIO() + with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err): + with TemporaryDirectory() as temp_dir: + # Don't highlight anything. + # See https://rich.readthedocs.io/en/stable/highlighting.html + with patch("pelican.console", new=Console(highlight=False)): + main(["-o", temp_dir, "pelican/tests/simple_content"]) + self.assertIn("Processed 1 article", out.getvalue()) + self.assertEqual("", err.getvalue()) From fd955ba05497c8add703fdb9d0e9788fc1aa90bf Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Sun, 16 Jun 2024 19:16:58 +0200 Subject: [PATCH 2/3] Show missing line numbers via `invoke coverage` Also includes a change that causes this command to return a failing status when coverage drops below its current value of 74.8%. --- tasks.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/tasks.py b/tasks.py index 64409e20..9a7564b2 100644 --- a/tasks.py +++ b/tasks.py @@ -47,7 +47,11 @@ def tests(c): @task def coverage(c): """Generate code coverage of running the test suite.""" - c.run(f"{VENV_BIN}/pytest --cov=pelican", pty=PTY) + c.run( + f"{VENV_BIN}/pytest --cov=pelican --cov-report term-missing " + "--cov-fail-under 74.8", + pty=PTY, + ) c.run(f"{VENV_BIN}/coverage html", pty=PTY) From e262990c689c6895a4724a7fd2c42412a8dca6a6 Mon Sep 17 00:00:00 2001 From: Justin Mayer Date: Sun, 16 Jun 2024 19:23:46 +0200 Subject: [PATCH 3/3] Tweak docs about test coverage and `git blame` --- docs/contribute.rst | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/contribute.rst b/docs/contribute.rst index 419ba80f..07cf998a 100644 --- a/docs/contribute.rst +++ b/docs/contribute.rst @@ -64,19 +64,26 @@ your bug fix or feature:: Now you can make changes to Pelican, its documentation, and/or other aspects of the project. -Setting up git blame --------------------- +Setting up ``git blame`` (optional) +----------------------------------- -``git blame`` annotates lines from a file with information about the pull request -that last modified it. Sweeping shallow changes (like formatting) can make that -information less useful, so we keep a list of such changes to be ignored. To set -that up in your repository:: +``git blame`` annotates lines in a file with information about the pull request +that last modified it. Sweeping shallow changes (like formatting) can make that +information less useful, so we keep a list of such changes to be ignored. Run the +following command to set this up in your repository, adding ``--global`` if you +want this setting to apply to all repositories:: git config blame.ignoreRevsFile .git-blame-ignore-revs -For more information, see here_. +As noted in a `useful article`_ about ``git blame``, there are other related +settings you may find to be beneficial:: -.. _here: https://www.michaelheap.com/git-ignore-rev/ + # Add `?` to any lines that have had a commit skipped using --ignore-rev + git config --global blame.markIgnoredLines true + # Add `*` to any lines that were added in a skipped commit and can not be attributed + git config --global blame.markUnblamableLines true + +.. _useful article: https://www.michaelheap.com/git-ignore-rev/ Running the test suite ---------------------- @@ -125,16 +132,17 @@ environments. Running a code coverage report ------------------------------ -The code is more likely to stay robust if it is tested. -coverage_ is a library that measures how much of the code is tested. -To run it:: +Code is more likely to stay robust if it is tested. Coverage_ is a library that +measures how much of the code is tested. To run it:: invoke coverage + +This will show overall coverage, coverage per file, and even line-by-line coverage. +There is also an HTML report available:: + open htmlcov/index.html -The HTML will show overall coverage, coverage per file, and even line-by-line coverage. - -.. _coverage: https://github.com/nedbat/coveragepy +.. _Coverage: https://github.com/nedbat/coveragepy Building the docs -----------------