Merge pull request #5 from evolvedbinary/develop2

Further small improvements
cityEHR · Nov 1, 2024 · 753e701 · 753e701
2 parents 89b6a3d + 09b8631
commit 753e701
Show file tree

Hide file tree

Showing 9 changed files with 165 additions and 16 deletions.
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
@@ -1,7 +1,7 @@
 name: pages
 on:
   push:
-    branches: ["main"]
+    branches: ["main", "develop"]
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -31,7 +31,7 @@ jobs:
       - name: Generate website (XSLT)
         id: generate
         # Override Maven properties for the Petal button url
-        run: mvn -B -Dpetal.api-url=https://petal.evolvedbinary.com -Dpetal.github-org-name=evolvedbinary -Dpetal.github-repo-name=cityehr-documentation -Dpetal.github-branch=develop -Dpetal.referrer-base-url=https://evolvedbinary.github.io/cityehr-documentation package -Pquick-start-guide-website
+        run: mvn -B -Dpetal.api-url=https://dev.petal.evolvedbinary.com -Dpetal.github-org-name=evolvedbinary -Dpetal.github-repo-name=cityehr-documentation -Dpetal.github-branch=develop -Dpetal.referrer-base-url=https://evolvedbinary.github.io/cityehr-documentation package -Pquick-start-guide-website
       - name: Setup Pages
         uses: actions/configure-pages@v5
       - name: Upload pages artifact

diff --git a/README.md b/README.md
@@ -0,0 +1,42 @@
+# cityEHR Documentation
+[![Build Status](https://github.com/cityehr/cityehr-documentation/actions/workflows/ci.yml/badge.svg)](https://github.com/cityehr/cityehr-documentation/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-CC%20BY%20NC%20SA%204.0-blue.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)
+
+This respository contains the documentation for cityEHR. The documentation is authored in [LwDITA](https://dita-lang.org/lwdita/capabilities/capabilities) XDITA format.
+
+When the source code of a document is updated in GitHub, we use GitHub Actions to automatically render a new HTML and PDF version of the documentation.
+
+
+## Documents
+
+| Title  | Source Location | Renderings |
+|---|---|---|
+| Quick Start Guide | [cityehr-quick-start-guide/src/main/lwdita/quickstart-guide-modular](cityehr-quick-start-guide/src/main/lwdita/quickstart-guide-modular) | [HTML](https://cityehr.github.io/cityehr-documentation/) / [PDF](https://cityehr.github.io/cityehr-documentation/quickstart-guide.pdf) |
+
+
+## Developing the Documentation
+
+If you wish to build the documentation on your own computer, you will need the following tools installed:
+
+* [Git](https://git-scm.com/)
+* [Java JDK](https://bell-sw.com/pages/downloads/) version 8 (or newer)
+* [Apache Maven](https://maven.apache.org/) 3.6 (or newer)
+
+1. If you have not already done so, clone the respoistory:
+```bash
+$ git clone https://github.com/cityehr/cityehr-documentation.git
+```
+
+2. Enter the clone folder:
+```bash
+$ cd cityehr-documentation
+```
+
+3. Run the following command to have Maven (mvn) render a new PDF and HTML version of the documentation:
+```bash
+$ mvn clean package -Pquick-start-guide-website
+```
+
+You can find the rendered versions of the documentation in the `target/` sub-folder of each module. For example:
+* `cityehr-quick-start-guide/target/quickstart-guide.pdf`
+* `cityehr-quick-start-guide/target/website/index.html`
diff --git a/cityehr-quick-start-guide/pom.xml b/cityehr-quick-start-guide/pom.xml
@@ -128,6 +128,39 @@
                     </execution>
                 </executions>
             </plugin>
+
+            <plugin>
+                <groupId>io.xspec.maven</groupId>
+                <artifactId>xspec-maven-plugin</artifactId>
+                <version>2.2.0</version>
+                <dependencies>
+                    <dependency>
+                        <groupId>net.sf.saxon</groupId>
+                        <artifactId>Saxon-HE</artifactId>
+                        <!-- Not yet compatible with Saxon 12, see: https://github.com/xspec/xspec-maven-plugin-1/issues/79 --> 
+                        <version>10.9</version>
+                    </dependency>
+                    <dependency>
+                        <!-- Not yet compatible with XSpec 3, see: https://github.com/xspec/xspec-maven-plugin-1/issues/79 -->
+                        <groupId>io.xspec</groupId>
+                        <artifactId>xspec</artifactId>
+                        <version>2.3.2</version>
+                    </dependency>
+                    <dependency>
+                         <!-- See: https://github.com/xspec/xspec-maven-plugin-1/issues/73 -->
+                        <groupId>commons-io</groupId>
+                        <artifactId>commons-io</artifactId>
+                        <version>2.11.0</version>
+                    </dependency>
+                </dependencies>
+                <executions>
+                    <execution>
+                        <id>xspec-tests</id>
+                        <phase>test</phase>
+                        <goals><goal>run-xspec</goal></goals>
+                    </execution>
+                </executions>
+            </plugin>
 
             <plugin>
                 <groupId>org.codehaus.mojo</groupId>

diff --git a/...-quick-start-guide/src/main/lwdita/quickstart-guide-modular/images/by-nc-sa.png b/...-quick-start-guide/src/main/lwdita/quickstart-guide-modular/images/by-nc-sa.png
diff --git a/cityehr-quick-start-guide/src/main/lwdita/quickstart-guide-modular/quickstart-guide.ditamap b/cityehr-quick-start-guide/src/main/lwdita/quickstart-guide-modular/quickstart-guide.ditamap
@@ -4,6 +4,11 @@
 <map id="topic_vkq_5nv_vcc">
    <topicmeta>
       <navtitle>Quick Start Guide</navtitle>
+      <othermeta name="SPDX-License-Identifier" content="CC-BY-NC-SA-4.0"/>
+      <othermeta name="dcterms:license" content="Creative Commons Attribution NonCommercial ShareAlike 4.0"/>
+      <othermeta name="dcterms:license" content="https://creativecommons.org/licenses/by-nc-sa/4.0/"/>
+      <othermeta name="dcterms:rights" content="Copyright 2023 Seven Informatics Limited"/>
+      <othermeta name="dcterms:rightsHolder" content="https://seveninformatics.com"/>
    </topicmeta>
    <topicref href="introduction.dita"/>
    <topicref href="verify-install.dita"/>

diff --git a/cityehr-quick-start-guide/src/main/xslt/create-map-html.xslt b/cityehr-quick-start-guide/src/main/xslt/create-map-html.xslt
@@ -31,21 +31,22 @@
   <xsl:variable name="topicrefs" as="element(topicref)+" select="doc($map-uri)/map/topicref"/>
 
   <xsl:template match="map">
-    <html>
+    <html xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/">
       <head>
         <xsl:call-template name="hcom:meta">
           <xsl:with-param name="authors" select="$authors"/>
           <xsl:with-param name="created-date" select="$map-date"/>
           <xsl:with-param name="modified-date" select="$map-date"/>
         </xsl:call-template>
       </head>
-      <body>
+      <body about="">
         <div id="cover-page">
           <div id="cover-page-logo">
             <img src="images/cityehr-logo.png"/>
           </div>
+          <xsl:apply-templates select="topicmeta" mode="cover-page"/>
         </div>
-        <article>
+        <article typeof="cc:Work">
           <time datetime="{$map-date}" pubdate="pubdate"></time>
           <xsl:apply-templates select="topicmeta" mode="body"/>
           <xsl:if test="exists($download-pdf-filename)">
@@ -61,12 +62,24 @@
     <xsl:apply-templates select="navtitle" mode="#current"/>
   </xsl:template>
 
+  <xsl:template match="topicmeta" mode="cover-page">
+    <div id="license" style="display: flex; align-items: center; justify-content: left">
+      <div id="license-image" style="max-width: 100%; max-height:100%;">
+        <a rel="license" href="{othermeta[@name eq 'dcterms:license'][2]/@content}"><img src="images/by-nc-sa.png" width="30%"/></a>
+      </div>
+      <div id="license-text" style="padding-left: 8pt; font-size: 8pt;">
+        <p><a property="cc:attributionName" rel="cc:attributionURL" href="{othermeta[@name eq 'dcterms:rightsHolder']/@content}"><xsl:value-of select="othermeta[@name eq 'dcterms:rights']/@content"/></a></p>
+        <p><a rel="license" href="{othermeta[@name eq 'dcterms:license'][2]/@content}"><xsl:value-of select="othermeta[@name eq 'dcterms:license'][1]/@content"/></a></p>
+      </div>
+    </div>
+  </xsl:template>
+
   <xsl:template match="navtitle" mode="metadata">
     <title><xsl:value-of select="."/></title>
   </xsl:template>
 
   <xsl:template match="navtitle" mode="body">
-    <h1><xsl:value-of select="."/></h1>
+    <h1 property="dct:title"><xsl:value-of select="."/></h1>
   </xsl:template>
 
   <!-- Create a new HTML file for each topic that is referenced -->

diff --git a/cityehr-quick-start-guide/src/main/xslt/create-map-pdf.xslt b/cityehr-quick-start-guide/src/main/xslt/create-map-pdf.xslt
@@ -44,7 +44,19 @@
 
   <!-- COVER PAGE FOOTER -->
   <xsl:template match="/map/topicmeta" mode="cover-page-footer">
-    <fo:block/>
+    <fo:block-container position="absolute">
+      <fo:block>
+        <fo:basic-link external-destination="{othermeta[@name eq 'dcterms:license'][2]/@content}"><fo:external-graphic src="{com:abs-uri(., 'images/by-nc-sa.png')}"/></fo:basic-link>
+      </fo:block>
+    </fo:block-container>
+    <fo:block-container position="absolute" margin-left="110pt" display-align="after" font-size="8pt">
+      <fo:block text-align="left">
+        <fo:basic-link external-destination="{othermeta[@name eq 'dcterms:rightsHolder']/@content}"><xsl:value-of select="othermeta[@name eq 'dcterms:rights']/@content"/></fo:basic-link>
+      </fo:block>
+      <fo:block text-align="left">
+        <fo:basic-link external-destination="{othermeta[@name eq 'dcterms:license'][2]/@content}"><xsl:value-of select="othermeta[@name eq 'dcterms:license'][1]/@content"/></fo:basic-link>
+      </fo:block>
+    </fo:block-container>
   </xsl:template>
 
   <!-- COVERPAGE SEQUENCE METADATA -->

diff --git a/cityehr-quick-start-guide/src/main/xslt/create-topic-html.xslt b/cityehr-quick-start-guide/src/main/xslt/create-topic-html.xslt
@@ -18,11 +18,11 @@
 
   <xsl:output method="html" version="5.0" encoding="UTF-8" indent="yes"/>
 
-  <xsl:param name="petal-api-url" />
-  <xsl:param name="petal-github-org-name" />
-  <xsl:param name="petal-github-repo-name" />
-  <xsl:param name="petal-github-branch" />
-  <xsl:param name="petal-referrer-base-url" />
+  <xsl:param name="petal-api-url"           as="xs:string" required="yes"/>
+  <xsl:param name="petal-github-org-name"   as="xs:string" required="yes"/>
+  <xsl:param name="petal-github-repo-name"  as="xs:string" required="yes"/>
+  <xsl:param name="petal-github-branch"     as="xs:string" required="yes"/>
+  <xsl:param name="petal-referrer-base-url" as="xs:string" required="yes"/>
 
   <xsl:variable name="authors" as="xs:string+" select="('John Chelsom', 'Stephanie Cabrera', 'Catriona Hopper', 'Jennifer Ramirez')"/>
 
@@ -40,7 +40,7 @@
 
         <!-- Petal Edit Button -->
         <div id="petal-edit-page-button">
-          <a href="{htop:petal-edit-url(.)}">
+          <a href="{htop:petal-edit-url(com:document-uri(.), $petal-api-url, $petal-github-org-name, $petal-github-repo-name, $petal-github-branch, $petal-referrer-base-url)}">
             <input type="button" value="Edit this page"/>
           </a>
         </div>
@@ -138,9 +138,15 @@
     Generates an Edit button URL for Petal
   -->
   <xsl:function name="htop:petal-edit-url" as="xs:string">
-    <xsl:param name="topic" as="element(topic)" required="yes"/>
-    <xsl:variable name="petal-source-file-uri" select="com:document-uri($topic)" />
-    <xsl:variable name="petal-source-file" select="substring-after($petal-source-file-uri, concat($petal-github-repo-name, '/'))" />
+    <xsl:param name="petal-source-file-uri"   as="xs:string" required="yes"/>
+    <xsl:param name="petal-api-url"           as="xs:string" required="yes"/>
+    <xsl:param name="petal-github-org-name"   as="xs:string" required="yes"/>
+    <xsl:param name="petal-github-repo-name"  as="xs:string" required="yes"/>
+    <xsl:param name="petal-github-branch"     as="xs:string" required="yes"/>
+    <xsl:param name="petal-referrer-base-url" as="xs:string" required="yes"/>
+
+    <xsl:variable name="petal-source-file-uri-tokens" select="tokenize($petal-source-file-uri, concat($petal-github-repo-name, '/'))" />
+    <xsl:variable name="petal-source-file" select="$petal-source-file-uri-tokens[last()]" />
     <xsl:variable name="petal-webpage-filename" select="hcom:dita-filename-to-html(com:filename($petal-source-file-uri))" />
     <xsl:sequence select="concat($petal-api-url, '?ghrepo=', $petal-github-org-name, '/', $petal-github-repo-name, '&amp;source=', $petal-source-file, '&amp;branch=', $petal-github-branch, '&amp;referer=', $petal-referrer-base-url, '/', $petal-webpage-filename)" />
   </xsl:function>

diff --git a/cityehr-quick-start-guide/src/test/xspec/create-topic-html.xspec b/cityehr-quick-start-guide/src/test/xspec/create-topic-html.xspec
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<x:description
+  xmlns:x="http://www.jenitennison.com/xslt/xspec"
+  xmlns:xs="http://www.w3.org/2001/XMLSchema"
+  xmlns:htop="http://cityehr/html/topic"
+  stylesheet="../../main/xslt/create-topic-html.xslt">
+
+  <x:param name="petal-api-url"           as="xs:string">https://petal.evolvedbinary.com</x:param>
+  <x:param name="petal-github-org-name"   as="xs:string">evolvedbinary</x:param>
+  <x:param name="petal-github-repo-name"  as="xs:string">cityehr-documentation</x:param>
+  <x:param name="petal-github-branch"     as="xs:string">develop</x:param>
+  <x:param name="petal-referrer-base-url" as="xs:string">https://evolvedbinary.github.io/cityehr-documentation</x:param>
+
+  <x:scenario label="Scenario for testing the petal-edit-url function with source file from local filesytem">
+    <x:call function="htop:petal-edit-url">
+      <x:param name="petal-source-file-uri"   as="xs:string">file:/Users/aretter/code/evolvedbinary/customers/cityehr/cityehr-documentation/cityehr-quick-start-guide/src/main/lwdita/quickstart-guide-modular/verify-install.dita</x:param>
+      <x:param name="petal-api-url"           as="xs:string">https://petal.evolvedbinary.com</x:param>
+      <x:param name="petal-github-org-name"   as="xs:string">evolvedbinary</x:param>
+      <x:param name="petal-github-repo-name"  as="xs:string">cityehr-documentation</x:param>
+      <x:param name="petal-github-branch"     as="xs:string">develop</x:param>
+      <x:param name="petal-referrer-base-url" as="xs:string">https://evolvedbinary.github.io/cityehr-documentation</x:param>
+    </x:call>
+    <x:expect label="Correct Petal Edit URL" select="'https://petal.evolvedbinary.com?ghrepo=evolvedbinary/cityehr-documentation&amp;source=cityehr-quick-start-guide/src/main/lwdita/quickstart-guide-modular/verify-install.dita&amp;branch=develop&amp;referer=https://evolvedbinary.github.io/cityehr-documentation/verify-install.html'"/>
+  </x:scenario>
+
+  <x:scenario label="Scenario for testing the petal-edit-url function with source file in GitHub Action container">
+    <x:call function="htop:petal-edit-url">
+      <x:param name="petal-source-file-uri"   as="xs:string">file:/home/runner/work/cityehr-documentation/cityehr-documentation/cityehr-quick-start-guide/src/main/lwdita/quickstart-guide-modular/verify-install.dita</x:param>
+      <x:param name="petal-api-url"           as="xs:string">https://petal.evolvedbinary.com</x:param>
+      <x:param name="petal-github-org-name"   as="xs:string">evolvedbinary</x:param>
+      <x:param name="petal-github-repo-name"  as="xs:string">cityehr-documentation</x:param>
+      <x:param name="petal-github-branch"     as="xs:string">develop</x:param>
+      <x:param name="petal-referrer-base-url" as="xs:string">https://evolvedbinary.github.io/cityehr-documentation</x:param>
+    </x:call>
+    <x:expect label="Correct Petal Edit URL" select="'https://petal.evolvedbinary.com?ghrepo=evolvedbinary/cityehr-documentation&amp;source=cityehr-quick-start-guide/src/main/lwdita/quickstart-guide-modular/verify-install.dita&amp;branch=develop&amp;referer=https://evolvedbinary.github.io/cityehr-documentation/verify-install.html'"/>
+  </x:scenario>
+
+</x:description>