Merge branch 'plugin' into 'main'

Plugin

See merge request mwasilew/2023-ZPRP!21

Author: Julia Maria Jodczyk

.gitignore

@@ -1,7 +1,9 @@
 venv/
 .venv/
 __pycache__/
-.vscode/*
+.vscode
 .pytest_cache/
 .tox/
-.hypothesis/
+.hypothesis/
+site
+demo/site

Makefile

@@ -26,4 +26,8 @@ clean:
 	rm -rf .tox
 	rm -rf .hypothesis
 
+plugin_demo:
+	cd demo
+	mkdocs serve
+
 .PHONY: tests clean pre_commit

README.md

@@ -12,43 +12,68 @@
 
 The plugin allows you to define image size categories and use them as tags in your documentation. The images annotated with tags will be resized to the size specified in the configuration file.
 
-### (Planned) Usage:
+### Installation:
+You can install the plugin using pip: `pip install mkdocs-image-formatter-plugin`
+
+
+### Usage:
+
+#### Prerequisites
+Plugin works by replacing your tags with attribute list that is later interpreted by `attr_list` markdown extension. Make sure you add it to `mkdocs.yaml` like so:
+```
+markdown_extensions:
+  - attr_list
+```
+
 
 #### Step 1.
 
 To configuration file add:
 
 ```
-- image_sizes:
-    - <tag_name>:
-        width: <size>
-        height: <size>
-    - <tag_name>:
-        width: <size>
-        height: <size>
+- image_formatter:
+    image_size:
+        <tag_name>:
+            width: <size>
+            height: <size>
+        <tag_name>:
+            width: <size>
+            height: <size>
 ```
 
 where different `tag_names` are the names of image size categories. Remember about measurement units (`px, %, etc.`) when specifying width and height.
 
 Example of correct configuration:
 
 ```
-- image_sizes:
-    - large:
-        width: 100px
-        height: 50px
-    - small:
-        width: 80px
-        height: 40px
+markdown_extensions:
+    - attr_list
+
+plugins:
+    - image-formatter:
+        image_size:
+            small:
+                height: 100px
+                width: 100px
+            big:
+                height: 200px
+                width: 200px
 ```
 
+
 #### Step 2:
 
 Annotate images in your documents with desired tags.
 
 Example:
 
 ```
-@small
-(../images/b.png)
+![MyImage]@small(../images/b.png)
 ```
+
+#### Info:
+If you accidentally use a tag that is not specified in the documentation, the tag will be removed and the image will be displayed with no additional formatting.
+
+
+### Demo:
+You can see the plugin in action after you clone this project to your local repository by executing `make plugin_demo` in the main directory.

demo/docs/img/Maine_coon.jpg

@@ -0,0 +1,55 @@
+# Cats
+
+## Introduction
+
+Cats are small, carnivorous mammals that are often kept as pets. They are known for their playful behavior, independent nature, and distinctive vocalizations. Here are some interesting facts about cats.
+
+## Breeds
+
+### 1. Persian Cat
+
+Persian cats are known for their long, luxurious fur and distinctive flat face. They are calm and enjoy lounging around the house.
+
+![Persian Cat]@small(./img/Persialainen.jpg)
+
+### 2. Siamese Cat
+
+Siamese cats are known for their striking blue almond-shaped eyes and short coat with color points. They are social and vocal.
+
+![Siamese Cat]@large(./img/Siam_lilacpoint.jpg)
+
+### 3. Maine Coon
+
+Maine Coon cats are one of the largest domestic cat breeds. They have tufted ears, bushy tails, and a thick, water-resistant coat.
+
+![Maine Coon]@small(./img/Maine_coon.jpg)
+
+## Behavior
+
+Cats exhibit various behaviors that make them unique and endearing as pets.
+
+### 1. Purring
+
+Cats purr when content or relaxed, and it is often associated with positive feelings.
+
+### 2. Kneading
+
+Kneading is a behavior where cats push their paws in and out against a soft surface. It's usually a sign of contentment.
+
+### 3. Hunting Instinct
+
+Cats are natural hunters, and even domesticated cats may display hunting behavior, such as stalking and pouncing.
+
+## Health
+
+### 1. Common Health Issues
+
+- **Hairballs:** Cats may develop hairballs from grooming themselves. Regular brushing can help reduce this issue.
+
+- **Dental Problems:** Dental care is crucial for cats. Regular teeth cleaning and dental check-ups are recommended.
+
+- **Obesity:** Overweight cats are prone to various health issues. A balanced diet and regular exercise are essential.
+
+## Conclusion
+
+Cats make wonderful companions, bringing joy and warmth to households worldwide. Understanding their behavior and providing proper care ensures a happy and healthy relationship with these fascinating creatures.

demo/docs/img/Persialainen.jpg

@@ -0,0 +1,23 @@
+site_name: Test with cats
+
+dev_addr: 127.0.0.1:8002
+
+theme:
+  name: "material"
+
+markdown_extensions:
+  - attr_list
+
+plugins:
+  - mkdocstrings
+  - image-formatter:
+      image_size:
+        small:
+          height: 100px
+          width: 100px
+        big:
+          height: 200px
+          width: 200px
+
+nav:
+  - Home: index.md

demo/docs/img/Siam_lilacpoint.jpg

@@ -37,13 +37,15 @@ Plug-in do MkDocs ułatwiający ustawianie rozmiarów obrazów w dokumentacji.
 - możliwość konfiguracji wymiarów obrazów:
   ```
   # Dodanie odpowiednich wpisów konfiguracyjnych:
-  image_sizes:
-    large:
-      - width: 100px
-        height: 50px
-    small:
-      - width: 80px
-        height: 40px
+  plugins:
+    - image_formatter:
+        image_size:
+            <tag_name>:
+                width: <size>
+                height: <size>
+            <tag_name>:
+                width: <size>
+                height: <size>
   ```
 - automatyczne ustawianie wymiarów obrazów poprzez zdefiniowane tagi
   ```

demo/docs/index.md

@@ -12,34 +12,50 @@
 
 The plugin allows you to define image size categories and use them as tags in your documentation. The images annotated with tags will be resized to the size specified in the configuration file.
 
-### (Planned) Usage:
+### Installation:
+You can install the plugin using pip: `pip install mkdocs-image-formatter-plugin`
+
+### Usage:
+
+#### Prerequisites
+Plugin works by replacing your tags with attribute list that is later interpreted by `attr_list` markdown extension. Make sure you add it to `mkdocs.yaml` like so:
+```
+markdown_extensions:
+  - attr_list
+```
 
 #### Step 1.
 
 To configuration file add:
 
 ```
-- image_sizes:
-    - <tag_name>:
-        width: <size>
-        height: <size>
-    - <tag_name>:
-        width: <size>
-        height: <size>
+- image_formatter:
+    image_size:
+        <tag_name>:
+            width: <size>
+            height: <size>
+        <tag_name>:
+            width: <size>
+            height: <size>
 ```
 
 where different `tag_names` are the names of image size categories. Remember about measurement units (`px, %, etc.`) when specifying width and height.
 
 Example of correct configuration:
 
 ```
-- image_sizes:
-    - large:
-        width: 100px
-        height: 50px
-    - small:
-        width: 80px
-        height: 40px
+markdown_extensions:
+    - attr_list
+
+plugins:
+    - image-formatter:
+        image_size:
+            small:
+                height: 100px
+                width: 100px
+            big:
+                height: 200px
+                width: 200px
 ```
 
 #### Step 2:
@@ -49,6 +65,9 @@ Annotate images in your documents with desired tags.
 Example:
 
 ```
-@small
-(../images/b.png)
+![MyImage]@small(../images/b.png)
 ```
+
+#### Info:
+If you accidentally use a tag that is not specified in the documentation, the tag will be removed and the image will be displayed with no additional formatting.
+

demo/mkdocs.yml

@@ -11,6 +11,9 @@
 import cssutils
 import logging
 from typing import Tuple
+from image_formatter.lexer.lexer import Lexer
+from image_formatter.image_properties_tag_replacer.image_properties_tag_replacer import ImagePropertiesTagReplacer
+from image_formatter.token_to_string_converter.token_to_string_converter import TokenToStringConverter
 
 WIDTH = "width"
 HEIGHT = "height"
@@ -44,7 +47,7 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig or None:
         """
         Verifies if tags are defined correctly. Each tag should specify width and height in valid CSS form.
         """
-        size_tags = config["image_formatter"]
+        size_tags = self.config["image_size"]
         for tag, options in size_tags.items():
             if WIDTH not in options or HEIGHT not in options:
                 raise mkdocs.config.base.ValidationError(f"width or height is missing from {tag} tag configuration")
@@ -56,6 +59,10 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig or None:
         return config
 
     def on_page_read_source(self, page: Page, config: MkDocsConfig) -> str or None:
-        # todo: using lexer, image_properties_tag_replacer and interpreter read user's docs and apply sizes specified in tags
-
-        pass
+        src_path = page.file.abs_src_path
+        with open(src_path, "r") as fp:
+            lexer = Lexer(fp)  # noqa
+            image_tag_replacer = ImagePropertiesTagReplacer(lexer, self.config["image_size"])
+            converter = TokenToStringConverter(image_tag_replacer)
+            result = converter.to_text()
+        return result

docs/DesignProposal.md

@@ -56,7 +56,7 @@ def parse_image_link_url(self, tag_token: Token) -> Token:
             self.next_token()
             return Token(TokenType.T_IMAGE_URL_WITH_PROPERTIES, url_token.position, formatted_url)
         else:
-            log.error(f"{ImagePropertiesTagReplacer.name()}: Failed to parse image link url.")
+            log.info(f"{ImagePropertiesTagReplacer.name()}: Failed to parse image link url.")
             self.error_handler.handle(UnexpectedTagException(TokenType.T_IMAGE_URL, self.curr_token.type))
             return tag_token
 
@@ -70,6 +70,9 @@ def add_tag_properties_to_url(self, tag_token: Token) -> str:
         Returns:
             str: image tag properties formatted to CSS
         """
+        if tag_token.string not in self.image_tags_properties:
+            log.info(f"{ImagePropertiesTagReplacer.name()}: {tag_token.string} is an unknown tag, removing formatting")
+            return self.curr_token.string
         properties = '{: style="'
         pairs = ";".join([f"{key}:{value}" for key, value in self.image_tags_properties[tag_token.string].items()])
         properties = properties + pairs + '"}'

docs/index.md

@@ -51,7 +51,7 @@ def __init__(
         self.max_int = max_int
         self.tag = tag
         self.special_signs = special_signs
-        self.newline_characters = newline_characters  # @TODO add hypothesis tests
+        self.newline_characters = newline_characters
         self.additional_path_signs = additional_path_signs
 
     @classmethod
@@ -305,7 +305,7 @@ def get_url_ending(self, string: str) -> str or None:
             return None
         string += self.current_char
         self.next_char()
-        while self.is_character() or self.current_char in self.additional_path_signs:  # @TODO add hypothesis tests
+        while self.is_character() or self.current_char in self.additional_path_signs:
             string += self.current_char
             self.next_char()
         log.info(f"{Lexer.name()}: Url ending built successfully.")