reformatted

Bump mkdocs-material from 9.4.6 to 9.4.8

.flake8

@@ -1,2 +0,0 @@
-[flake8]
-exclude = venv,build,docs

.github/workflows/python-package.yaml

@@ -21,13 +21,14 @@ jobs:
           - "3.9"
           - "3.10"
           - "3.11"
+          - "3.12"
         exclude:
           # 3.8 on windows fails due to some pip issue
           - os: windows-latest
             python-version: "3.8"
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
@@ -41,7 +42,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/setup-python@v4
       with:
         python-version: "3.x"
@@ -55,7 +56,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/setup-python@v4
       with:
         python-version: "3.x"
@@ -70,7 +71,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - uses: actions/setup-python@v4
       with:
         python-version: "3.x"

CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [2.2.1] -- 2023-11-11
+
+* fixed `suggests` to blag-doc
+
+## [2.2.0] -- 2023-11-05
+
+* switched from flake8 to ruff
+* added missing docstrings
+* fixed dev requirements in pyproject, still pointing to sphinx
+* added Python3.12 to test suite
+* removed debian/watch
+
+## [2.1.0] -- 2023-08-27
+
+* default theme: `img` have now `max-width: 100%` by default to avoid very
+  large images overflowing
+* packaging: explicitly list `templates`, `static` and `content` as packages
+  instead of relying on package-data for setuptools. additionally, created a
+  MANIFEST.in to add the contents of these directories here as well. the
+  automatic finding of namespace packages and packaga-data, currently does not
+  work as advertised in setuptools' docs
+* updated dependencies
+* created debian/watch
+
 ## [2.0.0] - 2023-06-16
 
 ### Breaking

MANIFEST.in

@@ -0,0 +1,3 @@
+recursive-include blag/content *
+recursive-include blag/static *
+recursive-include blag/templates *

Makefile

@@ -33,7 +33,7 @@ mypy: $(VENV)
 
 .PHONY: lint
 lint: $(VENV)
-	$(BIN)/flake8
+	$(BIN)/ruff check .
 
 .PHONY: build
 build: $(VENV)

README.md

@@ -16,7 +16,8 @@ blag is named after [the blag of the webcomic xkcd][blagxkcd].
 ## Features
 
 * Write content in [Markdown][]
-* Good looking default theme
+* Good looking default theme:
+  ![Blag Screenshot](blag/static/blag.png)
 * Theming support using [Jinja2][] templates
 * Generation of Atom feeds for blog content
 * Fenced code blocks and syntax highlighting using [Pygments][]

blag/blag.py

@@ -1,8 +1,6 @@
 #!/usr/bin/env python3
 
-"""blag's core methods.
+"""blag's core methods."""
-
-"""
 
 # remove when we don't support py38 anymore
 from __future__ import annotations
@@ -32,7 +30,7 @@ logging.basicConfig(
 
 
 def main(arguments: list[str] | None = None) -> None:
-    """Main entrypoint for the CLI.
+    """Run the CLI.
 
     This method parses the CLI arguments and executes the respective
     commands.
@@ -220,6 +218,7 @@ def build(args: argparse.Namespace) -> None:
     """
     os.makedirs(f"{args.output_dir}", exist_ok=True)
     convertibles = []
+    known_targets = []
     for root, dirnames, filenames in os.walk(args.input_dir):
         for filename in filenames:
             rel_src = os.path.relpath(
@@ -231,15 +230,22 @@ def build(args: argparse.Namespace) -> None:
                 rel_dst = rel_src
                 rel_dst = rel_dst[:-3] + ".html"
                 convertibles.append((rel_src, rel_dst))
+                known_targets.append(
+                    os.path.abspath(f"{args.output_dir}/{rel_dst}")
+                )
             else:
                 shutil.copy(
                     f"{args.input_dir}/{rel_src}",
                     f"{args.output_dir}/{rel_src}",
                 )
+                known_targets.append(
+                    os.path.abspath(f"{args.output_dir}/{rel_src}")
+                )
         for dirname in dirnames:
             # all directories are copied into the output directory
             path = os.path.relpath(f"{root}/{dirname}", start=args.input_dir)
             os.makedirs(f"{args.output_dir}/{path}", exist_ok=True)
+            known_targets.append(os.path.abspath(f"{args.output_dir}/{path}"))
 
     # copy static files over
     logger.info("Copying static files.")
@@ -275,6 +281,24 @@ def build(args: argparse.Namespace) -> None:
         article_template,
     )
 
+    # clean up files that should not be there
+    for root, dirnames, filenames in os.walk(args.output_dir):
+        for filename in filenames:
+            dst = os.path.abspath(f"{root}/{filename}")
+            if dst not in known_targets:
+                logger.info(f"deleting {dst}")
+                os.remove(dst)
+            else:
+                known_targets.remove(dst)
+        for dirname in dirnames:
+            dst = os.path.abspath(f"{root}/{dirname}")
+            if dst not in known_targets:
+                logger.info(f"deleting {dst}")
+                shutil.rmtree(dst)
+            else:
+                known_targets.remove(dst)
+    logger.debug(known_targets)
+
     generate_feed(
         articles,
         args.output_dir,
@@ -328,7 +352,7 @@ def process_markdown(
     for src, dst in convertibles:
         logger.debug(f"Processing {src}")
 
-        with open(f"{input_dir}/{src}", "r") as fh:
+        with open(f"{input_dir}/{src}") as fh:
             body = fh.read()
 
         content, meta = convert_markdown(md, body)

blag/content/second-post.md

@@ -7,3 +7,5 @@ Tags: blag
 ## Second Post
 
 This page serves no purpose :)
+
+![Blag Screenshot](blag.png)

blag/markdown.py

@@ -94,9 +94,10 @@ def convert_markdown(
 
 
 class MarkdownLinkTreeprocessor(Treeprocessor):
-    """Converts relative links to .md files to .html"""
+    """Converts relative links to .md files to .html."""
 
     def run(self, root: Element) -> Element:
+        """Process the ElementTree."""
         for element in root.iter():
             if element.tag == "a":
                 url = element.get("href")
@@ -109,6 +110,7 @@ class MarkdownLinkTreeprocessor(Treeprocessor):
         return root
 
     def convert(self, url: str) -> str:
+        """Convert relative .md-links to .html-links."""
         scheme, netloc, path, query, fragment = urlsplit(url)
         logger.debug(
             f"{url}: {scheme=} {netloc=} {path=} {query=} {fragment=}"
@@ -126,6 +128,7 @@ class MarkdownLinkExtension(Extension):
     """markdown.extension that converts relative .md- to .html-links."""
 
     def extendMarkdown(self, md: Markdown) -> None:
+        """Register the MarkdownLinkTreeprocessor."""
         md.treeprocessors.register(
             MarkdownLinkTreeprocessor(md),
             "mdlink",

blag/quickstart.py

@@ -1,6 +1,4 @@
-"""Helper methods for blag's quickstart command.
+"""Helper methods for blag's quickstart command."""
-
-"""
 
 # remove when we don't support py38 anymore
 from __future__ import annotations

blag/static/style.css

@@ -48,6 +48,10 @@ aside {
     color: var(--foreground-dim);
 }
 
+img {
+    max-width: 100%;
+}
+
 h1,
 h2,
 h3,

blag/version.py

@@ -1 +1,3 @@
-__VERSION__ = "2.0.0"
+"""Version information for the blag package."""
+
+__VERSION__ = "2.2.1"

debian/changelog

@@ -1,3 +1,33 @@
+blag (2.2.1) unstable; urgency=medium
+
+  * fixed suggests field to blag-doc (Closes: #1055769)
+
+ -- Bastian Venthur <venthur@debian.org>  Sat, 11 Nov 2023 10:57:06 +0100
+
+blag (2.2.0) unstable; urgency=medium
+
+  * switched from flake8 to ruff
+  * added missing docstrings
+  * fixed dev requirements in pyproject, still pointing to sphinx
+  * added Python3.12 to test suite
+  * removed watch file again
+
+ -- Bastian Venthur <venthur@debian.org>  Sun, 05 Nov 2023 17:08:09 +0100
+
+blag (2.1.0) unstable; urgency=medium
+
+  * default theme: `img` have now `max-width: 100%` by default to avoid very
+    large images overflowing
+  * packaging: explicitly list `templates`, `static` and `content` as packages
+    instead of relying on package-data for setuptools. additionally, created a
+    MANIFEST.in to add the contents of these directories here as well. the
+    automatic finding of namespace packages and packaga-data, currently does
+    not work as advertised in setuptools' docs
+  * updated dependencies
+  * created debian/watch
+
+ -- Bastian Venthur <venthur@debian.org>  Sun, 27 Aug 2023 15:27:39 +0200
+
 blag (2.0.0) unstable; urgency=medium
 
   * new upstream version

debian/control

@@ -31,7 +31,7 @@ Depends:
  ${python3:Depends},
  ${misc:Depends},
 Suggests:
- python-blag-doc,
+ blag-doc,
 Description: Blog-aware, static site generator
  Blag is a blog-aware, static site generator, written in Python. It supports
  the following features:

docs/index.md

@@ -17,6 +17,7 @@ blag is named after [the blag of the webcomic xkcd][blagxkcd].
 
 * Write content in [Markdown][]
 * Good looking default theme
+  ![Blag Screenshot](blag.png)
 * Theming support using [Jinja2][] templates
 * Generation of Atom feeds for blog content
 * Fenced code blocks and syntax highlighting using [Pygments][]

pyproject.toml

@@ -31,12 +31,14 @@ blag = "blag.blag:main"
 [project.optional-dependencies]
 dev = [
     "build",
-    "sphinx",
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings[python]",
     "twine",
     "wheel",
     "pytest",
     "pytest-cov",
-    "flake8",
+    "ruff",
     "mypy",
     "types-markdown",
 ]
@@ -47,16 +49,12 @@ version = {attr = "blag.__VERSION__" }
 [tool.setuptools]
 packages = [
     "blag",
+    "blag.templates",
+    "blag.static",
+    "blag.content",
     "tests",
 ]
 
-[tool.setuptools.package-data]
-blag = [
-    "templates/*",
-    "static/*",
-    "content/*",
-]
-
 [tool.pytest.ini_options]
 addopts = """
     --cov=blag
@@ -65,6 +63,21 @@ addopts = """
     --cov-report=term-missing:skip-covered
 """
 
+[tool.ruff]
+select = [
+    "F",        # pyflakes
+    "E", "W",   # pycodestyle
+    "C90",      # mccabe
+    "I",        # isort
+    "D",        # pydocstyle
+    "UP"        # pyupgrade
+]
+line-length = 79
+target-version = "py38"
+
+[tool.ruff.pydocstyle]
+convention = "numpy"
+
 [tool.mypy]
 files = "blag,tests"
 strict = true

requirements-dev.txt

@@ -1,11 +1,11 @@
-build==0.10.0
+build==1.0.3
-mkdocs==1.4.3
+mkdocs==1.5.3
-mkdocs-material==9.1.15
+mkdocs-material==9.4.8
-mkdocstrings[python]==0.20.0
+mkdocstrings[python]==0.23.0
 twine==4.0.2
-wheel==0.40.0
+wheel==0.41.3
-pytest==7.3.2
+pytest==7.4.3
-pytest-cov==4.0.0
+pytest-cov==4.1.0
-flake8==6.0.0
+ruff==0.1.5
-mypy==1.2.0
+mypy==1.6.1
-types-markdown==3.4.2.9
+types-markdown==3.5.0.1

requirements.txt

@@ -1,4 +1,4 @@
-markdown==3.4.3
+markdown==3.5.1
-feedgenerator==2.0.0
+feedgenerator==2.1.0
 jinja2==3.1.2
-pygments==2.15.1
+pygments==2.16.1

tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for blag."""

tests/conftest.py

@@ -1,3 +1,6 @@
+"""Pytest fixtures."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -14,6 +17,7 @@ from blag import blag, quickstart
 
 @pytest.fixture
 def environment(cleandir: str) -> Iterator[Environment]:
+    """Create a Jinja2 environment."""
     site = {
         "base_url": "site base_url",
         "title": "site title",
@@ -26,31 +30,37 @@ def environment(cleandir: str) -> Iterator[Environment]:
 
 @pytest.fixture
 def page_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 page-template."""
     yield environment.get_template("page.html")
 
 
 @pytest.fixture
 def article_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 article-template."""
     yield environment.get_template("article.html")
 
 
 @pytest.fixture
 def index_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 index-template."""
     yield environment.get_template("index.html")
 
 
 @pytest.fixture
 def archive_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 archive-template."""
     yield environment.get_template("archive.html")
 
 
 @pytest.fixture
 def tags_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 tags-template."""
     yield environment.get_template("tags.html")
 
 
 @pytest.fixture
 def tag_template(environment: Environment) -> Iterator[Template]:
+    """Create a Jinja2 tag-template."""
     yield environment.get_template("tag.html")
 
 
@@ -80,6 +90,7 @@ author = a. u. thor
 
 @pytest.fixture
 def args(cleandir: Callable[[], Iterator[str]]) -> Iterator[Namespace]:
+    """Create a Namespace with default arguments."""
     args = Namespace(
         input_dir="content",
         output_dir="build",

tests/test_blag.py

@@ -1,3 +1,6 @@
+"""Test blag."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -15,12 +18,14 @@ from blag import __VERSION__, blag
 
 
 def test_generate_feed(cleandir: str) -> None:
+    """Test generate_feed."""
     articles: list[tuple[str, dict[str, Any]]] = []
     blag.generate_feed(articles, "build", " ", " ", " ", " ")
     assert os.path.exists("build/atom.xml")
 
 
 def test_feed(cleandir: str) -> None:
+    """Test feed."""
     articles: list[tuple[str, dict[str, Any]]] = [
         (
             "dest1.html",
@@ -73,6 +78,7 @@ def test_feed(cleandir: str) -> None:
 
 
 def test_generate_feed_with_description(cleandir: str) -> None:
+    """Test generate_feed with description."""
     # if a description is provided, it will be used as the summary in
     # the feed, otherwise we simply use the title of the article
     articles: list[tuple[str, dict[str, Any]]] = [
@@ -98,6 +104,7 @@ def test_generate_feed_with_description(cleandir: str) -> None:
 
 
 def test_parse_args_build() -> None:
+    """Test parse_args with build."""
     # test default args
     args = blag.parse_args(["build"])
     assert args.input_dir == "content"
@@ -131,6 +138,7 @@ def test_parse_args_build() -> None:
 
 
 def test_get_config() -> None:
+    """Test get_config."""
     config = """
 [main]
 base_url = https://example.com/
@@ -180,6 +188,7 @@ author = a. u. thor
 
 
 def test_environment_factory(cleandir: str) -> None:
+    """Test environment_factory."""
     globals_: dict[str, object] = {"foo": "bar", "test": "me"}
     env = blag.environment_factory("templates", globals_=globals_)
     assert env.globals["foo"] == "bar"
@@ -191,6 +200,7 @@ def test_process_markdown(
     page_template: Template,
     article_template: Template,
 ) -> None:
+    """Test process_markdown."""
     page1 = """\
 title: some page
 
@@ -240,6 +250,7 @@ foo bar
 
 
 def test_build(args: Namespace) -> None:
+    """Test build."""
     page1 = """\
 title: some page
 
@@ -301,6 +312,22 @@ foo bar
     assert os.path.exists(f"{args.output_dir}/tags/bar.html")
 
 
+def test_remove_extra_files(args):
+    """Test that extra files are removed."""
+    # create a file and directory in output dir that have no corresponding
+    # source
+    file_path = f'{args.output_dir}/a'
+    dir_path = f'{args.output_dir}/b'
+    fh = open(file_path, 'w')
+    fh.close()
+    os.mkdir(dir_path)
+
+    blag.build(args)
+
+    assert not os.path.exists(file_path)
+    assert not os.path.exists(dir_path)
+
+
 @pytest.mark.parametrize(
     "template",
     [
@@ -313,16 +340,19 @@ foo bar
     ],
 )
 def test_missing_template_raises(template: str, args: Namespace) -> None:
+    """Test that missing templates raise SystemExit."""
     os.remove(f"templates/{template}")
     with pytest.raises(SystemExit):
         blag.build(args)
 
 
 def test_main(cleandir: str) -> None:
+    """Test main."""
     blag.main(["build"])
 
 
 def test_cli_version(capsys: CaptureFixture[str]) -> None:
+    """Test --version."""
     with pytest.raises(SystemExit) as ex:
         blag.main(["--version"])
     # normal system exit
@@ -333,6 +363,7 @@ def test_cli_version(capsys: CaptureFixture[str]) -> None:
 
 
 def test_cli_verbose(cleandir: str, caplog: LogCaptureFixture) -> None:
+    """Test --verbose."""
     blag.main(["build"])
     assert "DEBUG" not in caplog.text
 

tests/test_devserver.py

@@ -1,3 +1,6 @@
+"""Tests for the devserver module."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -11,6 +14,7 @@ from blag import devserver
 
 
 def test_get_last_modified(cleandir: str) -> None:
+    """Test get_last_modified."""
     # take initial time
     t1 = devserver.get_last_modified(["content"])
 
@@ -29,6 +33,7 @@ def test_get_last_modified(cleandir: str) -> None:
 
 
 def test_autoreload_builds_immediately(args: Namespace) -> None:
+    """Test autoreload builds immediately."""
     # create a dummy file that can be build
     with open("content/test.md", "w") as fh:
         fh.write("boo")
@@ -54,6 +59,7 @@ def test_autoreload_builds_immediately(args: Namespace) -> None:
     "ignore::pytest.PytestUnhandledThreadExceptionWarning"
 )
 def test_autoreload(args: Namespace) -> None:
+    """Test autoreload."""
     t = threading.Thread(
         target=devserver.autoreload,
         args=(args,),

tests/test_markdown.py

@@ -1,3 +1,6 @@
+"""Test markdown module."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -34,6 +37,7 @@ from blag.markdown import convert_markdown, markdown_factory
     ],
 )
 def test_convert_markdown_links(input_: str, expected: str) -> None:
+    """Test convert_markdown."""
     md = markdown_factory()
     html, _ = convert_markdown(md, input_)
     assert expected in html
@@ -51,6 +55,7 @@ def test_convert_markdown_links(input_: str, expected: str) -> None:
     ],
 )
 def test_dont_convert_normal_links(input_: str, expected: str) -> None:
+    """Test convert_markdown doesn't convert normal links."""
     md = markdown_factory()
     html, _ = convert_markdown(md, input_)
     assert expected in html
@@ -70,17 +75,20 @@ def test_dont_convert_normal_links(input_: str, expected: str) -> None:
     ],
 )
 def test_convert_metadata(input_: str, expected: dict[str, Any]) -> None:
+    """Test convert_markdown converts metadata correctly."""
     md = markdown_factory()
     _, meta = convert_markdown(md, input_)
     assert expected == meta
 
 
 def test_markdown_factory() -> None:
+    """Test markdown_factory."""
     md = markdown_factory()
     assert isinstance(md, markdown.Markdown)
 
 
 def test_smarty() -> None:
+    """Test smarty."""
     md = markdown_factory()
 
     md1 = """
@@ -95,6 +103,7 @@ this --- is -- a test ...
 
 
 def test_smarty_code() -> None:
+    """Test smarty doesn't touch code."""
     md = markdown_factory()
 
     md1 = """

tests/test_quickstart.py

@@ -1,3 +1,6 @@
+"""Tests for the quickstart module."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -9,21 +12,24 @@ from blag.quickstart import get_input, quickstart
 
 
 def test_get_input_default_answer(monkeypatch: MonkeyPatch) -> None:
+    """Test get_input with default answer."""
     monkeypatch.setattr("builtins.input", lambda x: "")
     answer = get_input("foo", "bar")
     assert answer == "bar"
 
 
 def test_get_input(monkeypatch: MonkeyPatch) -> None:
+    """Test get_input."""
     monkeypatch.setattr("builtins.input", lambda x: "baz")
     answer = get_input("foo", "bar")
     assert answer == "baz"
 
 
 def test_quickstart(cleandir: str, monkeypatch: MonkeyPatch) -> None:
+    """Test quickstart."""
     monkeypatch.setattr("builtins.input", lambda x: "foo")
     quickstart(None)
-    with open("config.ini", "r") as fh:
+    with open("config.ini") as fh:
         data = fh.read()
     assert "base_url = foo" in data
     assert "title = foo" in data

tests/test_templates.py

@@ -1,3 +1,6 @@
+"""Test the templates."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -7,6 +10,7 @@ from jinja2 import Template
 
 
 def test_page(page_template: Template) -> None:
+    """Test the page template."""
     ctx = {
         "content": "this is the content",
         "title": "this is the title",
@@ -17,6 +21,7 @@ def test_page(page_template: Template) -> None:
 
 
 def test_article(article_template: Template) -> None:
+    """Test the article template."""
     ctx = {
         "content": "this is the content",
         "title": "this is the title",
@@ -29,6 +34,7 @@ def test_article(article_template: Template) -> None:
 
 
 def test_index(index_template: Template) -> None:
+    """Test the index template."""
     entry = {
         "title": "this is a title",
         "dst": "https://example.com/link",
@@ -49,6 +55,7 @@ def test_index(index_template: Template) -> None:
 
 
 def test_archive(archive_template: Template) -> None:
+    """Test the archive template."""
     entry = {
         "title": "this is a title",
         "dst": "https://example.com/link",
@@ -67,6 +74,7 @@ def test_archive(archive_template: Template) -> None:
 
 
 def test_tags(tags_template: Template) -> None:
+    """Test the tags template."""
     tags = [("foo", 42)]
     ctx = {
         "tags": tags,
@@ -80,6 +88,7 @@ def test_tags(tags_template: Template) -> None:
 
 
 def test_tag(tag_template: Template) -> None:
+    """Test the tag template."""
     entry = {
         "title": "this is a title",
         "dst": "https://example.com/link",

tests/test_version.py

@@ -1,3 +1,6 @@
+"""Test the version module."""
+
+
 # remove when we don't support py38 anymore
 from __future__ import annotations
 
@@ -5,4 +8,5 @@ import blag
 
 
 def test_version() -> None:
+    """Test the version of the package."""
     assert isinstance(blag.__VERSION__, str)