Setup Javadoc hosting

.github/workflows/pages.yml

@@ -1,5 +1,5 @@
 # Simple workflow for deploying static content to GitHub Pages
-name: Deploy static content to Pages
+name: Deploy static content to GitHub Pages
 
 on:
   # Allows you to run this workflow manually from the Actions tab
@@ -11,68 +11,59 @@ on:
 jobs:
   build-docs:
     runs-on: ubuntu-latest
-    env:
-      JDK_VERSION: ${{ matrix.jdk }}
-
-    strategy:
-      fail-fast: false
-      matrix:
-        jdk: [ 17 ]
 
     steps:
     - name: Checkout
       uses: actions/checkout@v3
       with:
-        fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
+        fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
+        ref: host_javadocs
 
     - name: Set up Python 3.
-      uses: actions/setup-python@v3
+      uses: actions/setup-python@v4
       with:
         python-version: 3.9
 
+    - name: Install Python dependencies
+      run: |
+        pip install sphinx
+        pip install sphinx-rtd-theme
+
     - name: Set up JDK 17
-      uses: actions/setup-java@v2
+      uses: actions/setup-java@v3
       with:
         java-version: '17'
         distribution: 'adopt'
-
-    - name: Install dependencies
-      run: | 
-        pip install sphinx
-        pip install sphinx-rtd-theme
 
     - name: Build phenopacket-tools
-      run: ./mvnw -Prelease clean package
+      run: ./mvnw -Prelease -DskipTests package # We test elsewhere
 
-    - name: Get CLI JAR file
-      id: cli-jar
-      uses: ielis/Path-lister-action@try_pattern
-      with:
-          path: "phenopacket-tools-cli/target/"
-          # The pattern should match two types of inputs:
-          #  - bla-bla-1.2.3.jar          (release)
-          #  - bla-bla-1.2.3-SNAPSHOT.jar (snapshot)
-          # Using named groups below in attempt to improve legibility.
-          regex: ".*(?P<semantic_version>\\d\\.\\d\\.\\d)(?P<snapshot>-SNAPSHOT)?\\.jar$"
-
-    - name: Output results
-      id: jar-file
-      run: |
-        echo "Found ${{ steps.cli-jar.outputs.path_count }} file(s) with this extension:"
-        for i in ${{ steps.cli-jar.outputs.paths }}; do
-        echo $i
-        done
-
     - name: Generate examples and build documentation
-      run: | 
-        java -jar ${{ steps.cli-jar.outputs.paths }} examples
-        make yaml-docs -B
-        mkdir gh-pages gh-pages/examples
+      run: |
+        ## Init the target folder. 
+        # We will put all site documentation there.
+        mkdir -p gh-pages
         touch gh-pages/.nojekyll
+
+        ## Copy Javadoc
+        # Copy aggregated Javadoc into `apidocs` folder. 
+        # The aggregated docs are built by Maven in `package` phase.
+        cp -r target/site/apidocs ./gh-pages/apidocs 
+
+        ## Generate examples
+        # Find the CLI jar and run the `examples` command.
+        pxfcli="phenopacket-tools-cli"
+        find ${pxfcli}/target \
+             -regex "^${pxfcli}/target/${pxfcli}-[0-9]\.[0-9]\.[0-9]\(-SNAPSHOT\)?\.jar$" \
+             -exec java -jar {} examples --output gh-pages/examples \;
+
+        ## Build the docs
+        # Generate the HTML pages and move the generated content into the target folder. 
         cd docs/ 
-        sphinx-build -b html . _build
-        cp -r _build/* ../gh-pages/
-        cp -r yaml/* ../gh-pages/examples
+        make html
+        mv _build/html/* ../gh-pages/
+        cd ..
+
 
     - name: Deploy documentation.
       if: ${{ github.event_name == 'push' }}

README.md

@@ -1,54 +1,31 @@
-# phenopacket-tools
-
-[![GitHub release](https://img.shields.io/github/release/phenopackets/phenopacket-tools.svg)](https://github.com/phenopackets/phenopacket-tools/releases)
 [![Java CI](https://github.com/phenopackets/phenopacket-tools/workflows/Java%20CI/badge.svg)](https://github.com/phenopackets/phenopacket-tools/actions/workflows/main.yml)
+[![GitHub release](https://img.shields.io/github/release/phenopackets/phenopacket-tools.svg)](https://github.com/phenopackets/phenopacket-tools/releases)
+[![Javadoc](https://javadoc.io/badge2/org.phenopackets.phenopackettools/phenopacket-tools-core/javadoc.svg)](https://javadoc.io/doc/org.phenopackets.phenopackettools)
 
-Multimodule Java library/app that contains a "streamlined builder" module, a v1 to v2 converter app, a validator API and a JSON validator. 
-
-Both library and app requires Java 17 or better to run.
-
-## Phenopacket tools CLI
-
-The cli application works in a standard UNIX-like manner. 
+# Phenopacket-tools
 
-```shell
-cd phenopacket-tools
-./mvnw package
-alias pfx-tools="java -jar $(pwd)/phenopacket-tools-cli/target/phenopacket-tools-cli-@project.version@.jar"
-pfx-tools --help
-```
+*Phenopacket-tools* is an open-source Java library and command-line interface (CLI) application for construction, conversion, 
+and validation of phenopackets. 
 
-### Example Phenopackets
-The ``examples`` command in the CLI module writes a series of example phenopackets to a directory.
+The library simplifies construction of phenopackets by providing concise builders, 
+programmatic shortcuts, and predefined building blocks (ontology classes) for commonly used elements 
+such as anatomical organs, age of onset, biospecimen type, and clinical modifiers. 
 
-The command creates `phenopackets`, `families` and `cohorts` sub-folders in the provided directory to write 
-example *phenopackets*, *families*, and *cohorts*.
+The library validates the basic syntax and semantic requirements of the Phenopacket Schema as well 
+as the adherence to additional user-defined requirements. 
 
-```shell
-# create sub-folders folder and write the messages to the current directory by default
-pfx-tools examples
-# or write explicitly to the current directory
-pfx-tools examples -o .
-# or write to another directory
-pfx-tools examples --output ~/phenopacket-examples
-```
+## Documentation
 
-### Validate Phenopacket JSON files
+The documentation includes a [Tutorial](http://phenopackets.org/phenopacket-tools/tutorial.html) showing 
+how to use the CLI, 
+a comprehensive [CLI user guide](http://phenopackets.org/phenopacket-tools/cli.html),
+a [Library user guide](http://phenopackets.org/phenopacket-tools),
+and the [Java API documentation](https://javadoc.io/doc/org.phenopackets.phenopackettools).
 
-```shell
-# validate a single phenopacket 
-pfx-tools validate phenopacket ~/phenopacket-examples/phenopackets/covid.json
-# or all the phenopacket json files in a directory
-pfx-tools validate phenopacket ~/phenopacket-examples/phenopackets/*.json
-# or all families
-pfx-tools validate family ~/phenopacket-examples/families/*.json
-```
+## Availability
 
-### Convert Phenopacket versions
+Most users should download the latest distribution archive from the [Releases page](https://github.com/phenopackets/phenopacket-tools/releases).
 
-```shell
-pfx-tools convert phenopacket.json
-```
+## Issues
 
-### API
-A Javadoc description of the API of phenopacket-tools is available [here](https://javadoc.io/doc/org.phenopackets.phenopackettools).
+Comments, questions or issues? Feel free to submit a ticket to our [GitHub tracker](https://github.com/phenopackets/phenopacket-tools/issues).

docs/cli.rst

@@ -1,29 +1,29 @@
 .. _rstcli:
 
-============================
-Command line interface (CLI)
-============================
+======================
+Command-line interface
+======================
 
-*phenopacket-tools* CLI provides functionality for viewing, conversion and validation
+*Phenopacket-tools* command-line interface (CLI) provides functionality for viewing, conversion and validation
 of the top-level elements of Phenopacket schema. This document describes how to set up the CLI application
 on Linux, Mac and Windows environments.
 
 .. note::
-  *phenopacket-tools* is written in Java 17 and requires Java 17 or newer to run.
+  *Phenopacket-tools* is written in Java 17 and requires Java 17 or newer to run.
 
-*phenopacket-tools* is distributed as a standalone executable Java Archive (JAR) file. The application requires
+*Phenopacket-tools* is distributed as a standalone executable Java Archive (JAR) file. The application requires
 no special installation procedure if Java 17 or better is available in your environment.
 
 Setup
 ~~~~~
 
-Most users should *download* the distribution ZIP file with precompiled JAR file from *phenopacket-tools* release page.
+Most users should *download* the distribution ZIP file with precompiled JAR file from *Phenopacket-tools* release page.
 However, it is also possible to *build* the JAR from sources.
 
 Download
 ^^^^^^^^
 
-*phenopacket-tools* JAR is provided in the distribution ZIP file as part of *phenopacket-tools*' release schedule
+*Phenopacket-tools* JAR is provided in the distribution ZIP file as part of *Phenopacket-tools*' release schedule
 from `Releases <https://github.com/phenopackets/phenopacket-tools/releases>`_.
 
 The ZIP archive contains the executable JAR file along with README and example phenopackets required to run the setup
@@ -38,7 +38,7 @@ There are 2 requirements for building the app from sources:
 * **Java Development Kit** (JDK) 17 or newer must be present in the environment and ``$JAVA_HOME`` variable must point
   to JDK's location. See `Installing Apache Maven <https://maven.apache.org/install.html>`_ for more details regarding
   setting up JDK and ``$JAVA_HOME`` on your system.
-* *phenopacket-tools* leverages several open-source Java libraries and a **working internet connection**
+* *Phenopacket-tools* leverages several open-source Java libraries and a **working internet connection**
   is required to download the libraries.
 
 Run the following commands to check out the stable source code and to build the application::
@@ -49,13 +49,13 @@ Run the following commands to check out the stable source code and to build the
 
 After a successful build, a distribution ZIP file "phenopacket-tools-cli-|release|-distribution.zip"
 will be created in the ``phenopacket-tools-cli/target`` directory. Use the ZIP archive in the same way as the archive
-downloaded from *phenopacket-tools* releases.
+downloaded from *Phenopacket-tools* releases.
 
 
 Commands
 ~~~~~~~~
 
-*phenopacket-tools* CLI provides the following commands:
+*Phenopacket-tools* CLI provides the following commands:
 
 * ``examples`` - generate examples of the top-level elements
 * ``convert`` - convert top-level elements from *v1* to *v2* format
@@ -66,7 +66,7 @@ into the provided directory. The ``convert`` and ``validate`` commands, despite
 a similar manner. The parts shared by the both command are be described in greater detail
 in the ``convert`` command section.
 
-In the next sections, we will run *phenopacket-tools* by using the following alias::
+In the next sections, we will run *Phenopacket-tools* by using the following alias::
 
   $ alias pxf="java -jar phenopacket-tools-cli-${project.version}.jar"
 
@@ -110,7 +110,7 @@ We can convert a *v1* phenopacket into *v2* by running::
 
 
 
-*phenopacket-tools* makes an educated guess to determine if the input is in *JSON*, *Protobuf*, or *YAML* format.
+*Phenopacket-tools* makes an educated guess to determine if the input is in *JSON*, *Protobuf*, or *YAML* format.
 The guessing is, however, naive and can fail in parsing e.g. gzipped *JSON* file. Turn of the format guessing
 by providing the ``-f | --format`` option::
 

docs/index.rst

@@ -36,11 +36,11 @@ how to use the CLI application on your system.
    :caption: Contents:
 
    tutorial
+   cli
    creating
    validation
    converting
    constants
-   cli
 
 
 .. figure:: https://onlinelibrary.wiley.com/cms/asset/1cc0a141-da65-45a3-b7b0-6316b7b02069/ggn2202200016-fig-0002-m.jpg

pom.xml

@@ -8,8 +8,12 @@
     <artifactId>phenopacket-tools</artifactId>
     <version>0.4.7</version>
 
+    <name>Phenopacket-tools</name>
+    <description>An app and library for building, conversion and validation of GA4GH Phenopackets</description>
     <packaging>pom</packaging>
 
+    <url>https://phenopackets.org/phenopacket-tools</url>
+
     <prerequisites>
         <maven>3.6.0</maven>
     </prerequisites>
@@ -267,11 +271,21 @@
                             </configuration>
                             <executions>
                                 <execution>
+                                    <!-- Prepare Javadoc JARs for Maven Central. -->
                                     <id>attach-javadocs</id>
                                     <goals>
                                         <goal>jar</goal>
                                     </goals>
                                 </execution>
+                                <execution>
+                                    <!-- Aggregate Javadoc for hosting at the project site. -->
+                                    <id>aggregate</id>
+                                    <goals>
+                                        <goal>aggregate</goal>
+                                    </goals>
+                                    <phase>package</phase>
+                                    <inherited>false</inherited>
+                                </execution>
                             </executions>
                         </plugin>
                         <plugin>