Merge pull request #223 from JavaEden/dev

Release 0.15.3

Author: cjbrooks12

OrchidCore/src/main/java/com/eden/orchid/api/theme/pages/OrchidReference.java

@@ -36,6 +36,11 @@ public final class OrchidReference {
      */
     private String extension;
 
+    /**
+     * The querystring for linking to external pages
+     */
+    private String query;
+
     /**
      * The output extension of the file.
      */
@@ -85,6 +90,7 @@ public OrchidReference(OrchidReference source) {
         this.fileName = source.fileName;
         this.extension = source.extension;
         this.id = source.id;
+        this.query = source.query;
         this.title = source.title;
         this.usePrettyUrl = source.usePrettyUrl;
     }
@@ -197,7 +203,23 @@ public String getPath() {
     public String getPathSegment(int segmentIndex) {
         String path = getPath();
         String[] segments = path.split("/");
-        return segments[segmentIndex];
+
+        final int actualIndex;
+        // we have a positive index
+        if(segmentIndex >= 0 && segmentIndex <= segments.length - 1) {
+            actualIndex = segmentIndex;
+        }
+        // we have a negative index, search from end
+        else if(segmentIndex < 0 && Math.abs(segmentIndex) <= segments.length) {
+            actualIndex = segments.length - Math.abs(segmentIndex);
+        }
+
+        // index not in range
+        else {
+            throw new ArrayIndexOutOfBoundsException(segmentIndex);
+        }
+
+        return segments[actualIndex];
     }
 
     public String[] getPathSegments() {
@@ -270,6 +292,11 @@ public String getServerPath() {
             output += id;
         }
 
+        if (!EdenUtils.isEmpty(query)) {
+            output += "?";
+            output += query;
+        }
+
         return OrchidUtils.normalizePath(output);
     }
 
@@ -315,6 +342,7 @@ public JSONObject toJSON() {
         referenceJson.put("fileName", this.fileName);
         referenceJson.put("extension", this.extension);
         referenceJson.put("id", this.id);
+        referenceJson.put("query", this.query);
         referenceJson.put("title", this.title);
         referenceJson.put("usePrettyUrl", this.usePrettyUrl);
 
@@ -328,6 +356,7 @@ public static OrchidReference fromJSON(OrchidContext context, JSONObject source)
         newReference.fileName = source.optString("fileName");
         newReference.extension = source.optString("extension");
         newReference.id = source.optString("id");
+        newReference.query = source.optString("query");
         newReference.title = source.optString("title");
         newReference.usePrettyUrl = source.optBoolean("usePrettyUrl");
         return newReference;
@@ -349,6 +378,11 @@ public static OrchidReference fromUrl(OrchidContext context, String title, Strin
             newReference.path = OrchidUtils.normalizePath(parsedUrl.getPath().replaceAll(FilenameUtils.getName(parsedUrl.getPath()), ""));
             newReference.title = title;
             newReference.extension = FilenameUtils.getExtension(FilenameUtils.getName(url));
+            newReference.outputExtension = newReference.extension;
+            newReference.query = parsedUrl.getQuery();
+            newReference.id = parsedUrl.getRef();
+            newReference.setUsePrettyUrl(false);
+
             return newReference;
         }
         catch (Exception e) {
@@ -408,5 +442,13 @@ public void setUsePrettyUrl(boolean usePrettyUrl) {
         this.usePrettyUrl = usePrettyUrl;
     }
 
+    public String getQuery() {
+        return query;
+    }
+
+    public OrchidReference setQuery(String query) {
+        this.query = query;
+        return this;
+    }
 }
 

OrchidCore/src/main/kotlin/com/eden/orchid/impl/themes/menus/LinkMenuItem.kt

@@ -4,8 +4,8 @@ import com.eden.common.util.EdenUtils
 import com.eden.orchid.api.OrchidContext
 import com.eden.orchid.api.options.annotations.Description
 import com.eden.orchid.api.options.annotations.Option
-import com.eden.orchid.api.theme.menus.OrchidMenuFactory
 import com.eden.orchid.api.theme.menus.MenuItem
+import com.eden.orchid.api.theme.menus.OrchidMenuFactory
 import com.eden.orchid.api.theme.pages.OrchidExternalPage
 import com.eden.orchid.api.theme.pages.OrchidReference
 import com.eden.orchid.utilities.OrchidUtils
@@ -36,12 +36,18 @@ constructor(
 
         if (!EdenUtils.isEmpty(title) && !EdenUtils.isEmpty(url)) {
             var reference: OrchidReference? = null
+
+            // if link is just a slash, it is a link to the homepage
             if (url == "/") {
                 url = context.baseUrl
             }
+
+            // if the URL is not external, apply this site's base URL to make it absolute
             else if (!OrchidUtils.isExternal(url)) {
                 url = OrchidUtils.applyBaseUrl(context, url)
             }
+
+            // if the link is an ID, it should be a link to the current page at that ID
             else if (url.startsWith("#")) {
                 reference = OrchidReference(page.reference)
                 reference.id = url.substring(1)

OrchidCore/src/orchid/resources/changelog/0_15_3.md

@@ -0,0 +1,7 @@
+---
+version: '0.15.3'
+---
+
+- Updates OrchidBible dependency to hit correct endpoints and improves usability
+- Parses external URLs better
+- Passes command line args directly through to Dokka so Gradle can supply the proper documentation classpath

OrchidCore/src/orchid/resources/config.yml

@@ -46,3 +46,8 @@ services:
     stages:
       - type: githubReleases
         repo: 'JavaEden/Orchid'
+
+kotlindoc:
+  sourceDirs:
+    - '../../main/java'
+    - '../../main/kotlin'

OrchidCore/src/orchid/resources/pages/plugins/OrchidKotlindoc/index.md

@@ -37,4 +37,29 @@ services:
 {% endhighlight %}
 
 Orchid itself is written in Kotlin and documented with this Kotlindoc plugin. You can preview the generated 
-documentation {{anchor('here', 'com.eden.orchid')}}.
+documentation {{anchor('here', 'com.eden.orchid')}}.
+
+### Dokka Configuration
+
+This plugin delegates to Dokka to provide the documentation model. It will fetch the necessary jars and [run Dokka using
+the command line](https://github.com/Kotlin/dokka#using-the-command-line), and you are able to add any additional 
+arguments you wish. 
+
+First, you may specify the `--kotlindocClasspath` flag to Orchid, which will forward this value to Dokka's `-classpath`
+arg. Example usage when running Orchid from Gradle looks like the following:
+
+{% highlight 'groovy' %}
+orchid {
+    ...
+    args = ["--kotlindocClasspath", getModuleClasspathString()]
+}
+{% endhighlight %}
+
+In addition, you may specify a full list of args in your `config.yml` which will be passed-through to Dokka. 
+
+{% highlight 'yaml' %}
+kotlindoc:
+  args:
+    - '-classpath'
+    - '...'
+{% endhighlight %}

OrchidCore/src/orchid/resources/templates/includes/officialPlugin.peb

@@ -2,7 +2,7 @@
 
 {%- block homepageUrl  -%}{{- page.link~'/docs' -}}                                                           {%- endblock -%}
 {%- block homepageText -%}Full Documentation                                                                  {%- endblock -%}
-{%- block dependency   -%}io.github.javaeden.orchid:{{- page.reference.originalFileName -}}:{{ site.version }}{%- endblock -%}
+{%- block dependency   -%}io.github.javaeden.orchid:{{- page.reference.pathSegments|last -}}:{{ site.version }}{%- endblock -%}
 {%- block vcsUrl       -%}https://github.com/JavaEden/Orchid                                                  {%- endblock -%}
 {%- block vcsIcon      -%}github                                                                              {%- endblock -%}
 {%- block vcsRepo      -%}JavaEden/Orchid                                                                     {%- endblock -%}

OrchidCore/src/orchid/resources/templates/includes/officialTheme.peb

@@ -2,7 +2,7 @@
 
 {%- block homepageUrl  -%}{{- page.link~'/docs' -}}                                                           {%- endblock -%}
 {%- block homepageText -%}Full Documentation                                                                  {%- endblock -%}
-{%- block dependency   -%}io.github.javaeden.orchid:{{- page.reference.originalFileName -}}:{{ site.version }}{%- endblock -%}
+{%- block dependency   -%}io.github.javaeden.orchid:{{- page.reference.pathSegments|last -}}:{{ site.version }}{%- endblock -%}
 {%- block vcsUrl       -%}https://github.com/JavaEden/Orchid                                                  {%- endblock -%}
 {%- block vcsIcon      -%}github                                                                              {%- endblock -%}
 {%- block vcsRepo      -%}JavaEden/Orchid                                                                     {%- endblock -%}

OrchidCore/src/orchid/resources/wiki/user-manual/publication/deployment-pipelines.md

@@ -108,3 +108,4 @@ There are several publishers available in `OrchidCore`, but more may be availabl
 - {{anchor('Script')}} - Execute arbitrary shell scripts
 - {{anchor('Netlify')}} - Upload your site to Netlify
 - {{anchor('GitHub Pages')}} - Push your site to GitHub Pages 
+- {{anchor('GitHub Releases')}} - Create a release on Github 

OrchidCore/src/orchid/resources/wiki/user-manual/publication/github-pages.md

@@ -11,15 +11,16 @@ This publisher expects Git to be installed locally on your system, as it delegat
 directly to shell commands.
 {% endalert %}
 
-To use the `ghPages` publisher, you'll need to provide Orchid with a `githubToken` containing a Personal Access Token
-from Netlify. Since PATs are confidential and allow anyone who has it complete access to your account, you should set 
-this as an environment variable and add it to your Gradle orchid config from that variable rather than committing it to
-source control.
+To use the `githubReleases` publisher, you'll need to provide Orchid with a `githubToken` containing a Personal Access 
+Token from Github. Since PATs are confidential and allow anyone who has it complete access to your account, you should 
+set this as an environment variable and add it to your Gradle orchid config from that variable rather than committing it 
+to source control.
 
 {% highlight 'groovy' %}
 orchid {
     ...
-    args = ["githubToken ${System.getenv('GITHUB_TOKEN')}"]
+    githubToken = "${System.getenv('GITHUB_TOKEN')}" 
+    // or 'githubToken' in an environment variable without this line
 }
 {% endhighlight %}
 
@@ -39,6 +40,7 @@ services:
       - type: ghPages
         username: 'cjbrooks12'
         repo: 'JavaEden/Orchid'
+      #    or
       - type: ghPages
         username: 'cjbrooks12'
         repo: 'cjbrooks12.github.io' # becomes cjbrooks12/cjbrooks12.github.io 

OrchidCore/src/orchid/resources/wiki/user-manual/publication/github-releases.md

@@ -4,46 +4,35 @@ description: 'Create a Release on Github from your Changelog.'
 
 ## Description
 
-The `ghPages` Publisher allows you to upload your site to GithubPages.
+The `githubReleases` Publisher allows you to create a git tag and a Release on Github with notes from your latest 
+changelog entry.
 
-{% alert 'info' %}
-This publisher expects Git to be installed locally on your system, as it delegates the entire deployment process 
-directly to shell commands.
-{% endalert %}
-
-To use the `ghPages` publisher, you'll need to provide Orchid with a `githubToken` containing a Personal Access Token
-from Netlify. Since PATs are confidential and allow anyone who has it complete access to your account, you should set 
-this as an environment variable and add it to your Gradle orchid config from that variable rather than committing it to
-source control.
+To use the `githubReleases` publisher, you'll need to provide Orchid with a `githubToken` containing a Personal Access 
+Token from Github. Since PATs are confidential and allow anyone who has it complete access to your account, you should 
+set this as an environment variable and add it to your Gradle orchid config from that variable rather than committing it 
+to source control.
 
 {% highlight 'groovy' %}
 orchid {
     ...
-    args = ["githubToken ${System.getenv('GITHUB_TOKEN')}"]
+    githubToken = "${System.getenv('GITHUB_TOKEN')}" 
+    // or 'githubToken' in an environment variable without this line
 }
 {% endhighlight %}
 
-After your PAT is set up, you'll need to set up your repo on GitHub with a `gh-pages` branch. Orchid will initialize a 
-new local git repo and push it to this branch, overwriting anything currently in that branch. 
-
-The `username` property is the user which issued the PAT, and it is also the organization hosting the repository on 
-GitHub. You can authenticate with a different user than is hosting the repository by setting the `repo` as 
-`username/repo`.
+The release will be created on the repo specified in the publisher config, specified at `repo` as `username/repo`. The 
+account the PAT was created for must have write acess to this repo. 
 
 ## Example Usage
 
 {% highlight 'yaml' %}
 services:
-  publications: 
-    stages: 
-      - type: ghPages
-        username: 'cjbrooks12'
+  publications:
+    stages:
+      githubReleases:
         repo: 'JavaEden/Orchid'
-      - type: ghPages
-        username: 'cjbrooks12'
-        repo: 'cjbrooks12.github.io' # becomes cjbrooks12/cjbrooks12.github.io 
 {% endhighlight %}
 
 ## API Documentation
 
-{% docs className='com.eden.orchid.impl.publication.GithubPagesPublisher' tableClass='table' tableLeaderClass='hidden' %}
+{% docs className='com.eden.orchid.changelog.publication.GithubReleasesPublisher' tableClass='table' tableLeaderClass='hidden' %}

OrchidCore/src/orchid/resources/wiki/user-manual/publication/netlify.md

@@ -14,7 +14,7 @@ source control.
 {% highlight 'groovy' %}
 orchid {
     ...
-    args = ["netlifyToken ${System.getenv('NETLIFY_TOKEN')}"]
+    args = ["netlifyToken", "${System.getenv('NETLIFY_TOKEN')}"]
 }
 {% endhighlight %}
 

OrchidCore/src/test/kotlin/com/eden/orchid/api/theme/pages/OrchidReferenceTest.kt

@@ -0,0 +1,80 @@
+package com.eden.orchid.api.theme.pages
+
+import com.caseyjbrooks.clog.Clog
+import com.eden.orchid.api.OrchidContext
+import org.junit.jupiter.api.BeforeEach
+import org.junit.jupiter.params.ParameterizedTest
+import org.junit.jupiter.params.provider.CsvSource
+import org.mockito.Mockito.mock
+import strikt.api.expectThat
+import strikt.api.expectThrows
+import strikt.assertions.isEqualTo
+
+class OrchidReferenceTest {
+
+    lateinit var context: OrchidContext
+
+    @BeforeEach
+    internal fun setUp() {
+        context = mock(OrchidContext::class.java)
+    }
+
+    @ParameterizedTest
+    @CsvSource(
+        "/one/two/three/four/five, 0, one",
+        "/one/two/three/four/five, 1, two",
+        "/one/two/three/four/five, 2, three",
+        "/one/two/three/four/five, 3, four",
+        "/one/two/three/four/five, 4, five",
+
+        "/one/two/three/four/five, -5, one",
+        "/one/two/three/four/five, -4, two",
+        "/one/two/three/four/five, -3, three",
+        "/one/two/three/four/five, -2, four",
+        "/one/two/three/four/five, -1, five"
+    )
+    fun testGetPathSegment(path: String, index: Int, segment: String) {
+        val ref = OrchidReference(context, path)
+
+        expectThat(ref.getPathSegment(index)).isEqualTo(segment)
+    }
+
+    @ParameterizedTest
+    @CsvSource(
+        "/one/two/three/four/five, 5",
+        "/one/two/three/four/five, -6"
+    )
+    fun testGetPathSegmentThrowing(path: String, index: Int) {
+        val ref = OrchidReference(context, path)
+
+        expectThrows<ArrayIndexOutOfBoundsException> { ref.getPathSegment(index) }
+    }
+
+    @ParameterizedTest
+    @CsvSource(
+        // basic examples
+        "http://www.example.com/example                    ,      ,                   ",
+        "https://www.example.com/example                   ,      ,                   ",
+        "https://www.example.com/example#one               , one,                     ",
+        "https://www.example.com/example?one=two           ,      , one=two           ",
+        "https://www.example.com/example?one=two&three=four,      , one=two&three=four",
+
+        // more complex examples
+        "http://www.example.com/example.js                 ,      ,                   ",
+        "http://www.example.com/example/index              ,      ,                   ",
+        "http://www.example.com/example/index.js           ,      ,                   ",
+        "http://www.example.com/example/index.html         ,      ,                   "
+    )
+    fun testParsingExternalUrls(original: String, id: String?, query: String?) {
+        val ref = OrchidReference.fromUrl(context, "", original)
+
+        Clog.getInstance().setMinPriority(Clog.Priority.VERBOSE)
+
+        expectThat(ref) {
+            get { this.toString() }.isEqualTo(original)
+            get { this.id }.isEqualTo(id)
+            get { this.query }.isEqualTo(query)
+        }
+    }
+
+}