Merge pull request #5 from bcgov/pr5

updating stable to include latest fixes including adding "latest update" plugin

.github/workflows/test.yml

@@ -0,0 +1,30 @@
+name: Unit Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  run_tests:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10' 
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest
+
+      - name: Test with pytest
+        run: |
+          pytest

.gitignore

@@ -41,3 +41,4 @@ Thumbs.db
 /.idea/*
 /test.sh
 __pycache__
+.vscode/

Dockerfile

@@ -7,11 +7,10 @@ RUN  apt-get update &&  apt-get install python3-pip python3.11-venv jq -y && pyt
 RUN \
 /.virtualenvs/techdocs/bin/pip install mkdocs-techdocs-core==1.* && \
 /.virtualenvs/techdocs/bin/pip install yq && \
-/.virtualenvs/techdocs/bin/pip install markdown-inline-mermaid==1.0.3 && \
 /.virtualenvs/techdocs/bin/pip install mkdocs-ezlinks-plugin==0.1.14 && \
 /.virtualenvs/techdocs/bin/pip install mkpatcher==1.0.2 && \
-npm install -g @mermaid-js/mermaid-cli && \
-npm install -g @techdocs/cli@1.7.0 && \
+/.virtualenvs/techdocs/bin/pip install mkdocs-git-revision-date-localized-plugin && \
+npm install -g @techdocs/cli@1.8.1 && \
 mkdir /mkpatcher_scripts
 
 COPY entrypoint.sh /entrypoint.sh

action.yml

@@ -2,13 +2,11 @@ name: Build and Publish TechDocs
 description: Build and Publish TechDocs to DevHub
 inputs:
   publish:
-    description: Flag to control whether generated documentation is published to shared
-      bucket or not.
+    description: Flag to control whether generated documentation is published to shared bucket or not.
     required: true
     default: 'false'
   production:
-    description: Flag to control whether generated documentation is published to production
-      folder in shared bucket.
+    description: Flag to control whether generated documentation is published to production folder in shared bucket.
     required: true
     default: 'false'
   bucket_name:
@@ -21,12 +19,11 @@ inputs:
     description: Secret access key id use to authenticate with S3 endpoint.
     required: false
   s3_region:
-    description: Region value to use with S3 endpoint. This is for compatibility with
-      AWS SDK, but may not be used by all S3 implementations.
+    description: Region value to use with S3 endpoint. This is for compatibility with AWS SDK, but may not be used by all S3 implementations.
     required: false
   s3_endpoint:
     description: Address of S3 endpoint
     required: false
 runs:
   using: docker
-  image: docker://ghcr.io/bcgov/devhub-techdocs-publish:v0.0.19
+  image: docker://ghcr.io/bcgov/devhub-techdocs-publish:v0.0.21

docs/index.md

@@ -53,20 +53,26 @@ jobs:
 
 If you have a local folder or repo containing markdown content for which you wish to view a "preview" to get an idea of what it would look like in DevHub, you can use the Docker image, as shown below.
 
+Change to your local clone of your documentation repo:
+
 ```shell
 cd <your folder or repo with mkdocs.yml and docs folder>
-# docker / colima
+```
+
+If you're using `docker` or `colima`, pull the image and use it to preview your content as follows:
+```shell
 docker pull ghcr.io/bcgov/devhub-techdocs-publish:v0.0.19
 docker run -it -p 3000:3000 -v $(pwd):/github/workspace ghcr.io/bcgov/devhub-techdocs-publish preview
+```
 
-# podman
+If you're using `podman`, pull the image and use it to preview your content as follows:
+```
 podman pull ghcr.io/bcgov/devhub-techdocs-publish:v0.0.19
 podman run -it -p 3000:3000 -v $(pwd):/github/workspace ghcr.io/bcgov/devhub-techdocs-publish preview
 ```
 
 The above commands will:
 
 - generate HTML from your markdown documents using a standard set of plugins/extensions for DevHub compatibility
-- start a "preview" web server on [http://localhost:3000](http://localhost:3000) for you to review your content. 
-
+- start a "preview" web server on [http://localhost:3000](http://localhost:3000) for you to review your content.
 

mkdocs.yml

@@ -4,9 +4,8 @@ repo_url: https://github.com/bcgov/devhub-techdocs-publish
 plugins:
     - techdocs-core
     - ezlinks
-
+    - git-revision-date-localized
 markdown_extensions:
-    - markdown_inline_mermaid
     - md_in_html
     -   mkpatcher:
             location: patcher.py

mkpatcher_scripts/patcher.py

@@ -4,14 +4,18 @@
 
 def patch(lines):
 	new_lines = []
+	in_code_block = False
 	for index, line in enumerate(lines):
 		# if we don't do any twiddling, carry the line through as-is
 		new_line = line
 
 		# match lines starting with a dash or bullet, with leading white space or not
 		bullet = re.match(r"^[\s]*[-\*]{1}\s", new_line)
+		code_block = re.match(r"^[\s]*(?!`{4})`{3}", new_line)
+		if code_block:
+			in_code_block = not(in_code_block)
 
-		if bullet:
+		if bullet and not(in_code_block):
 			logging.debug(f"Found line starting with bullet: '{new_line}'")
 
 			# match lines with leading white space

mkpatcher_scripts/test_patcher.py

@@ -0,0 +1,86 @@
+from patcher import patch
+
+def test_ignores_bullets_in_code_blocks():
+  input = """```yaml
+example:
+  - item1 
+  - item2
+``` 
+"""
+  result = patch(input.splitlines(True))
+  result = ''.join(result)
+  assert result == input
+
+def test_bullets_formatted_outside_of_code_blocks():
+  input = """introduction sentence
+  - item1 
+  - item2
+"""  
+  expected_result = """introduction sentence
+
+- item1 
+  - item2
+"""  
+
+  result = patch(input.splitlines(True))
+  result = ''.join(result)
+  assert result == expected_result
+
+# 4 backticks escapes code blocks. Used in markdown when you want to display the markdown for a code block
+def test_ignore_bullets_in_escaped_code_blocks():
+  input = """````
+```yaml
+example:
+  - item1 
+  - item2
+``` 
+````
+""" 
+  result = patch(input.splitlines(True))
+  result = ''.join(result)
+  assert result == input
+
+# Test a more complex case. Escaped code block, bulletted list and another code block
+def test_code_blocks_and_bullets():
+  input = """````
+```yaml
+example:
+  - item1 
+  - item2
+``` 
+````
+another line
+ - bullet 1
+- bullet 2
+
+more code
+```
+something:
+- x
+- y
+```
+""" 
+
+  expected_result =  """````
+```yaml
+example:
+  - item1 
+  - item2
+``` 
+````
+another line
+
+- bullet 1
+- bullet 2
+
+more code
+```
+something:
+- x
+- y
+```
+""" 
+
+  result = patch(input.splitlines(True))
+  result = ''.join(result)
+  assert result == expected_result

tag.sh

@@ -31,7 +31,7 @@ fi
 
 
 read -p "About to update action file to use new Docker tag '${TAG}'. Press any key to continue..."
-yq -y -i ".runs.image = \"docker://ghcr.io/bcgov/devhub-techdocs-publish:$TAG\"" action.yml
+yq -i ".runs.image = \"docker://ghcr.io/bcgov/devhub-techdocs-publish:$TAG\"" action.yml
 
 
 read -p "About to commit new action file and create new git tag '${TAG}'. Press any key to continue..."