format rendered tile html (#62)

ntno · web-flow · commit dd514529cb72 · 2023-01-12T10:58:35.000-05:00
* version bump
* see how grid looks with multiple tiles
* strip whitespace
* add example error
* add info about docker container setup
* more info on running tests locally
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -74,7 +74,7 @@ See 'Theme Updates' in [Developer Setup](DEVELOPER_README.md#theme-updates)
 
 ### Adding Tests
 
-See 'Add Tests' in [Developer Setup](DEVELOPER_README.md#add-tests)
+See 'Add Tests' in [Developer Setup](DEVELOPER_README.md#add-functional-tests)
 
 ## CI Information
 
diff --git a/DEVELOPER_README.md b/DEVELOPER_README.md
@@ -21,13 +21,18 @@ Use this readme to add a feature to this theme or to update the theme documentat
     - [Bump Theme Version](#bump-theme-version)
     - [Start Documentation Server with Local Theme](#start-documentation-server-with-local-theme)
     - [Make Updates](#make-updates)
-    - [Test Theme Build Locally](#test-theme-build-locally)
-    - [Add Tests](#add-tests)
+    - [Test Theme Build/Packaging Locally](#test-theme-buildpackaging-locally)
+    - [Add Functional Tests](#add-functional-tests)
     - [Push Changes and Create PR](#push-changes-and-create-pr-1)
     - [Review PR Build](#review-pr-build)
 
 
 ## Developer Setup
+Development for this project is done within [Docker containers].  Using Docker containers makes setup easy because all developer workspaces will have the same installed software / OS.  If there's a tool that is not available that you think would be helpful to add to the default container image, please feel free to [open an Issue](https://github.com/ntno/mkdocs-terminal/issues/new/choose) and start a discussion.  
+
+*Note*: All software besides the two prerequisites will be installed in the Docker container and not your machine.
+
+[Docker containers]: https://www.docker.com/resources/what-container/
 
 ### Prerequisites
 - install [docker](https://docs.docker.com/get-docker/)
@@ -48,6 +53,14 @@ make serve-docs
 You should be able to visit [http://0.0.0.0:8080/mkdocs-terminal/](http://0.0.0.0:8080/mkdocs-terminal/) in your browser and view the mkdocs-terminal documentation site.  
 
 If you get a `docker.sock: connect: permission denied` error, you probably need to start the Docker engine on your machine.  
+
+**Example Error**:
+```
+Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/json?all=1&filters=%7B%22label%22%3A%7B%22com.docker.compose.project%3Dmkdocs-terminal%22%3Atrue%7D%7D&limit=0": dial unix /var/run/docker.sock: connect: permission denied
+make: *** [ubuntu] Error 1
+```
+
+**Solution**:
 Open the Docker Desktop application and wait until the application indicates that the Docker engine is in a "running" state.  Then retry starting your docker container.  
 
 <img src="documentation/docs/img/developer-setup/engine-starting.png" width="600" title="Docker Engine Starting" alt="orange starting indicator at bottom left of Docker Desktop">
@@ -118,16 +131,32 @@ Update files in [terminal/](terminal/).  You should see changes loaded in [http:
   - confirm links are not broken
   - confirm existing components/features still work
 
-### Test Theme Build Locally
+### Test Theme Build/Packaging Locally
 Launch the project's ubuntu container and run tox build tests:
 
-```
+```bash
 make ubuntu
 make tox
 ```
 
-### Add Tests
-Test suite setup is in progress.  See [GitHub issue](https://github.com/ntno/mkdocs-terminal/issues/13) for details.  If you have experience creating automated tests for Jinja2 please consider making a contribution!  
+### Add Functional Tests
+If you are adding/changing theme functionality, please add a test to the relevant test class in [tests/](tests/).  You can run the test suite locally by using the commands described in this section.  
+
+After you have installed the required testing software you can rerun `make quick-tests` whenever you want to re-execute.
+
+```bash
+make ubuntu
+make install-test-prereqs
+make install-test-requirements
+make quick-tests
+```
+
+Remember to work in the project's [Docker container](#developer-setup) to avoid Python dependency conflicts.  Once you have run `make ubuntu`, your terminal prompt should include `root@CONTAINER_ID`:
+
+![Docker Container](documentation/docs/img/developer-setup/developer-container.png)
+
+
+Test suites can always be improved!  See [GitHub issue](https://github.com/ntno/mkdocs-terminal/issues/13) for current progress/discussion.  If you have experience creating automated tests for Jinja2 please consider making a contribution.  
 
 ### Push Changes and Create PR
 See [Work On Pull Request](https://github.com/susam/gitpr#work-on-pull-request) for help on adding/pushing changes to your feature branch.  
diff --git a/NOTES.md b/NOTES.md
@@ -35,4 +35,5 @@ Terminal for MkDocs' Tile Grid relies on the *meta*[^mkdocs-page-meta] attribute
   - img: https://picsum.photos/id/{id}/200/200  
 - to read: [Make for devops](https://alexharv074.github.io/2019/12/26/gnu-make-for-devops-engineers.html)  
 - to read: [testing bash scripts](https://alexharv074.github.io/2017/07/07/unit-testing-a-bash-script-with-shunit2.html)  
-- [pytidylib](https://pythonhosted.org/pytidylib/)
+- [pytidylib](https://pythonhosted.org/pytidylib/)  
+- [jinja2 web render](https://j2live.ttl255.com/)  
diff --git a/documentation/docs/img/developer-setup/developer-container.png b/documentation/docs/img/developer-setup/developer-container.png
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "mkdocs-terminal",
-    "version": "1.3.0",
+    "version": "1.4.0",
     "description": "Terminal.css theme for MkDocs",
     "keywords": [
         "mkdocs",
diff --git a/requirements.test.txt b/requirements.test.txt
@@ -1,3 +1,4 @@
+flake8
 mkdocs
 pytest > 7
 pytidylib >= 0.3.2 
diff --git a/terminal/macros/tile-image.j2 b/terminal/macros/tile-image.j2
@@ -1,8 +1,6 @@
 {% macro make_image( tile ) -%}
-<img src="{{ tile.img_src }}" 
-    {% if tile.img_title is defined and tile.img_title|string|length %}title="{{ tile.img_title }}"{% endif %} 
-    alt="{{ tile.img_alt|default('', true ) }}"
-    {% if tile.img_width is defined and tile.img_width|string|length %}width="{{ tile.img_width }}"{% endif %} 
-    {% if tile.img_height is defined and tile.img_height|string|length %}height="{{ tile.img_height }}"{% endif %} 
->
+<img src="{{ tile.img_src }}" alt="{{ tile.img_alt|default('', true ) }}"
+    {%- if tile.img_title is defined and tile.img_title|string|length %} title="{{ tile.img_title }}"{% endif %} 
+    {%- if tile.img_width is defined and tile.img_width|string|length %} width="{{ tile.img_width }}"{% endif %} 
+    {%- if tile.img_height is defined and tile.img_height|string|length %} height="{{ tile.img_height }}"{% endif %} >
 {%- endmacro -%}
diff --git a/terminal/macros/tile-link.j2 b/terminal/macros/tile-link.j2
@@ -1,7 +1,5 @@
 {% macro make_link_start( tile ) -%}
 <a  href="{{ tile.link_href }}" 
-    {% if tile.link_title is defined and tile.link_title|string|length %}title="{{ tile.link_title }}"{% endif %} 
-    {% if tile.link_target is defined and tile.link_target|string|length %}target="{{ tile.link_target }}"{% endif %} 
->
+    {%- if tile.link_title is defined and tile.link_title|string|length %} title="{{ tile.link_title }}"{% endif %} 
+    {%- if tile.link_target is defined and tile.link_target|string|length %} target="{{ tile.link_target }}"{% endif %} >
 {%- endmacro -%}
-
diff --git a/terminal/macros/tile.j2 b/terminal/macros/tile.j2
@@ -1,51 +1,35 @@
+
 {% import 'macros/tile-image.j2' as image_helper %}
 {% import 'macros/tile-link.j2' as link_helper %}
-
-{% macro make_tile( tile ) -%}
-
-{% set ns = namespace(is_valid=false, has_link=false, has_image=false, has_caption=false) %}
-{% if tile.img_src is defined and tile.img_src|string|length %}
+{% macro make_tile( tile ) %}
+{%- set ns = namespace(is_valid=false, has_link=false, has_image=false, has_caption=false) -%}
+{%- if tile.img_src is defined and tile.img_src|string|length -%}
     {%- set ns.has_image = true -%}
-{% endif %}
-{% if tile.link_href is defined and tile.link_href|string|length %}
+{%- endif -%}
+{%- if tile.link_href is defined and tile.link_href|string|length -%}
     {%- set ns.has_link = true -%}
-{% endif %}
-{% if tile.caption is defined and tile.caption|string|length %}
+{%- endif -%}
+{%- if tile.caption is defined and tile.caption|string|length -%}
     {%- set ns.has_caption = true -%}
-{% endif %}
-{% if ns.has_link or ns.has_image %}
+{%- endif -%}
+{%- if ns.has_link or ns.has_image -%}
     {%- set ns.is_valid = true -%}
-{% endif %}
-
-
-{% if ns.is_valid %}
-<div 
-{% if tile.id is defined and tile.id|string|length %} 
-id="{{ tile.id }}" 
-{% endif %}
-class="terminal-mkdocs-tile {{ tile.class }}">
-    <figure>
-        {% if ns.has_link %} 
-             {{ link_helper.make_link_start(tile) }}
-        {% endif %}
-
-        {% if ns.has_image %} 
-            {{ image_helper.make_image(tile) }}
-        {% endif %}
-
-        {% if ns.has_link %}
-            {% if ns.has_image %} 
-                </a>
-            {% else %}
-            {{ tile.link_text|default(tile.link_href, true) }}</a>
-            {% endif %}
-        {% endif %}
-        
-        {% if ns.has_caption %}
-            <figcaption>{{ tile.caption|string|trim }}</figcaption>
-        {% endif %}
-    </figure>
-</div>
-{% endif %}
+{%- endif -%}
+{%- if ns.is_valid -%}
+    <div {% if tile.id is defined and tile.id|string|length %} id="{{ tile.id }}"{%- endif -%} class="terminal-mkdocs-tile {{ tile.class }}">
+        <figure>
+            {% if ns.has_link -%}{{ link_helper.make_link_start(tile) }}{% endif %}
+            {%- if ns.has_image %} 
+                    {{ image_helper.make_image(tile) }}
+            {%- endif -%}
+            {%- if ns.has_link -%}
+                {% if ns.has_image %} 
+            </a>{% else %}{{ tile.link_text|default(tile.link_href, true) }}</a>{%- endif -%}
+            {%- endif -%}
+            {%- if ns.has_caption %}
+        <figcaption>{{ tile.caption|string|trim }}</figcaption>
+            {%- endif %}
+        </figure>
+    </div>
+{%- endif -%}
 {%- endmacro -%}
-
diff --git a/terminal/partials/tiles.html b/terminal/partials/tiles.html
@@ -1,13 +1,12 @@
 {% import 'macros/tile.j2' as tile_helper %}
 
-{% if page and page.meta %}
-{% set show_tiles = "true" if page.meta.tiles %}
-{% endif %}
-
-{% if show_tiles %}
+{%- if page and page.meta -%}
+{%- set show_tiles = "true" if page.meta.tiles -%}
+{%- endif -%}
+{%- if show_tiles -%}
 <div class="terminal-mkdocs-tile-grid">
-    {%- for tile in page.meta.tiles -%}
+    {% for tile in page.meta.tiles -%}
     {{ tile_helper.make_tile( tile ) }}
-    {%- endfor %}
+    {% endfor %}
 </div>
-{% endif%}
+{%- endif -%}
diff --git a/terminal/theme_version.html b/terminal/theme_version.html
@@ -1 +1 @@
-<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-terminal-1.3.0">
+<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-terminal-1.4.0">
diff --git a/tests/test_grid.py b/tests/test_grid.py
@@ -0,0 +1,28 @@
+from tests.utils.html import check_html
+import pytest
+
+
+class TestGrid():
+
+    def test_grid_with_no_tiles_is_empty_string(self, env_with_terminal_loader):
+        grid_partial = env_with_terminal_loader.get_template("partials/tiles.html")
+        rendered_grid = grid_partial.render()
+        assert rendered_grid.strip() == ""
+
+    def test_grid_with_tiles(self, env_with_terminal_loader, minimal_linked_image_tile, minimal_image_tile, minimal_link_tile):
+        grid_partial = env_with_terminal_loader.get_template("partials/tiles.html")
+        context_data = {
+            "page": {
+                "meta": {
+                    "tiles": [minimal_image_tile, minimal_link_tile, minimal_linked_image_tile]
+                }
+            }
+        }
+
+        try:
+            grid_partial.new_context(context_data)
+            rendered_grid = grid_partial.render(context_data)
+            assert "class=\"terminal-mkdocs-tile-grid\">" in rendered_grid
+            assert len(check_html(rendered_grid)["errors"]) == 0
+        except Exception as ex:
+            pytest.fail(f"Got exception during render: {ex})")

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "mkdocs-terminal",`
`3`		`- "version": "1.3.0",`
	`3`	`+ "version": "1.4.0",`
`4`	`4`	`"description": "Terminal.css theme for MkDocs",`
`5`	`5`	`"keywords": [`
`6`	`6`	`"mkdocs",`
-Original file line number
+Diff line change
@@ @@ -1,3 +1,4 @@ @@
 +flake8
 mkdocs
 pytest > 7
 pytidylib >= 0.3.2