Merge pull request #181 from ielis/release-v1.0.0-RC3

Release v1.0.0 RC3

Author: ielis

.github/workflows/pages.yml

@@ -1,12 +1,12 @@
 # Simple workflow for deploying static content to GitHub Pages
-name: Deploy static content to GitHub Pages
+name: Deploy documentation to GitHub Pages
 
 on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
   # Runs on pushes targeting the main branch
   push:
-    branches: [ main ]
+    branches: [ main, develop ]
 
 jobs:
   build-docs:
@@ -34,9 +34,6 @@ jobs:
       with:
         java-version: '17'
         distribution: 'adopt'
-    
-    - name: Build phenopacket-tools
-      run: ./mvnw -Prelease -DskipTests package # We test elsewhere
 
     - name: Generate examples and build documentation
       run: |
@@ -45,33 +42,60 @@ jobs:
         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.
-        printf "Copying Javadocs from %s to %s\n" $(pwd)/target/site/apidocs $(pwd)/gh-pages/apidocs
-        cp -r target/site/apidocs ./gh-pages/apidocs 
+        function build_docs {
+          # The function will checkout a branch and build the Javadoc & documentation 
+          # into provided documentation directory.
+          BRANCH=${1}
+          DOCDIR=${2}
+        
+          git checkout ${BRANCH}
+          git fetch
+          git pull
+          ## Init the target folder.
+          # We will put all site documentation there.
+          mkdir -p gh-pages/${DOCDIR}
         
-        ## Generate examples
-        # Find the CLI jar and run the `examples` command.
-        jar=$(find phenopacket-tools-cli/target \
-          -regextype posix-extended \
-          -regex ".*[0-9]+\.[0-9]+\.[0-9]+(-RC[1-9][0-9]*)?\.jar$")
-        if [ -f "${jar}" ]; then
-          printf "Generating Phenopacket examples using ${jar}\n"
-          java -jar ${jar} examples -v --output-directory ./gh-pages/examples
-        else
-          printf "Could not find phenopacket-tools JAR file\n"
-          tree -L 3 .
-          exit 1
-        fi
+          ## Javadoc
+          # Build the aggregated Javadoc.
+          ./mvnw --quiet clean
+          ./mvnw --quiet -Ddoclint=none -Dinherited=false javadoc:aggregate
+          
+          # Copy aggregated Javadoc into `apidocs` folder.
+          APIDOCS=$(pwd)/gh-pages/${DOCDIR}/apidocs
+          printf "Copying Javadocs from %s to %s\n" $(pwd)/target/site/apidocs ${APIDOCS}
+          cp -r target/site/apidocs ${APIDOCS}
+          
+          ## Generate examples
+          # Find the CLI jar and run the `examples` command.
+          ./mvnw --quiet -Prelease -DskipTests package
+          jar=$(find phenopacket-tools-cli/target \
+            -regextype posix-extended \
+            -regex ".*[0-9]+\.[0-9]+\.[0-9]+(-RC[1-9][0-9]*)?(-SNAPSHOT)?\.jar$")
+          if [ -f "${jar}" ]; then
+            printf "Generating Phenopacket examples using ${jar}\n"
+            java -jar ${jar} examples -v --output-directory ./gh-pages/${DOCDIR}/examples
+          else
+            printf "Could not find phenopacket-tools JAR file\n"
+            tree -L 3 .
+            exit 1
+          fi
+          
+          ## Build the docs
+          # Generate the HTML pages and move the generated content into the target folder.
+          printf "Building the %s documentation\n" ${DOCDIR}
+          cd docs/
+          # Replace the `release_tag` placeholder to the right value in place. 
+          # This must be done *prior* generating docs in several files
+          sed -i "s/release_tag/${DOCDIR}/g" examples.rst
+          make clean html
+          cd ..
+          mv docs/_build/html/* gh-pages/${DOCDIR}
+        }
         
-        ## Build the docs
-        # Generate the HTML pages and move the generated content into the target folder.
-        printf "Building the documentation\n"
-        cd docs/ 
-        make html
-        mv _build/html/* ../gh-pages/
-        cd ..
+        # We store the docs for `master` in `stable` dir
+        build_docs main stable
+        # We store the docs for `develop` in `latest` dir
+        build_docs develop latest
 
 
     - name: Deploy documentation.

CHANGELOG.rst

@@ -6,8 +6,11 @@ Changelog
 -----
 
 * Update predefined constants, convenience functions and builders
-* Improve user guide, tutorial, and documentation
+* Improve user guide, tutorial, and documentation.
+  * Introduce *latest* and *stable* documentation branches
+  * Add showcase of apps that use phenopacket-tools to add more code examples
 * Run `MetaDataValidator` during base validation
+* Finalize JSON and YAML format sniffing
 * Fix example phenopackets
 
 0.4.7

README.md

@@ -15,27 +15,33 @@ as the adherence to additional user-defined requirements.
 
 ## Availability
 
-Most users should download the latest distribution archive from the [Releases page](https://github.com/phenopackets/phenopacket-tools/releases).
-Alternatively, *phenopacket-tools* can be built from source, as described in the user guide.
+### CLI application
 
-## Documentation
+A ZIP file with prebuilt CLI application is available for download from the [Releases page](https://github.com/phenopackets/phenopacket-tools/releases).
+Alternatively, the application can be built from source, as described in the library user guide (see the links below).
+
+### Library
 
-We provide the documentation for the latest release (`stable`) as well as the development version (`latest`).  
+We provide *phenopacket-tools* library for use in JVM-based applications. 
+We publish the JAR artifacts to public [Maven central](https://mvnrepository.com/artifact/org.phenopackets.phenopackettools) 
+repository, and we make the Javadoc API documentation available for the *latest.
+
+## Documentation
 
-The documentation includes a *Tutorial* showing how to use the CLI, a comprehensive *CLI user guide*, 
+We provide documentation with a *Tutorial* showing how to use the CLI, a comprehensive *CLI user guide*,
 a *Library user guide*, and the *Javadoc API documentation*.
 
-**Stable**
-- [Tutorial](http://phenopackets.org/phenopacket-tools/stable/tutorial.html)
-- [CLI user guide](http://phenopackets.org/phenopacket-tools/stable/cli.html)
-- [Library user guide](http://phenopackets.org/phenopacket-tools/stable)
-- [Javadoc API documentation](http://phenopackets.org/phenopacket-tools/stable/apidocs)
-
-**Latest**
-- [Tutorial](http://phenopackets.org/phenopacket-tools/latest/tutorial.html)
-- [CLI user guide](http://phenopackets.org/phenopacket-tools/latest/cli.html)
-- [Library user guide](http://phenopackets.org/phenopacket-tools/latest)
-- [Javadoc API documentation](http://phenopackets.org/phenopacket-tools/latest/apidocs)
+The documentation is published in two documentation branches:
+- **stable**: corresponds to the latest published release, and generally also to the last commit of the `main` Git branch
+  - [Tutorial](http://phenopackets.org/phenopacket-tools/stable/tutorial.html)
+  - [CLI user guide](http://phenopackets.org/phenopacket-tools/stable/cli.html)
+  - [Library user guide](http://phenopackets.org/phenopacket-tools/stable)
+  - [Javadoc API documentation](http://phenopackets.org/phenopacket-tools/stable/apidocs)
+- **latest**: corresponds to the bleeding edge code that is on the `develop` Git branch
+  - [Tutorial](http://phenopackets.org/phenopacket-tools/latest/tutorial.html)
+  - [CLI user guide](http://phenopackets.org/phenopacket-tools/latest/cli.html)
+  - [Library user guide](http://phenopackets.org/phenopacket-tools/latest)
+  - [Javadoc API documentation](http://phenopackets.org/phenopacket-tools/latest/apidocs)  
 
 ## Issues
 

docs/conf.py

@@ -33,7 +33,7 @@
 # The short X.Y version.
 version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.0-RC2'
+release = '1.0.0-RC3'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/examples.rst

@@ -6,6 +6,9 @@ Phenopackets Examples
 
 Example JSON and YAML files can be viewed for the following:
 
-* `Phenopackets <https://github.com/phenopackets/phenopacket-tools/tree/gh-pages/examples/phenopackets>`_
-* `Families <https://github.com/phenopackets/phenopacket-tools/tree/gh-pages/examples/families>`_
-* `Cohorts <https://github.com/phenopackets/phenopacket-tools/tree/gh-pages/examples/cohorts>`_
+.. Note that the `release_tag` is replaced by an actual doc version descriptor in `pages.yml` workflow
+
+* `Phenopackets <https://github.com/phenopackets/phenopacket-tools/tree/gh-pages/release_tag/examples/phenopackets>`_
+* `Families <https://github.com/phenopackets/phenopacket-tools/tree/gh-pages/release_tag/examples/families>`_
+* `Cohorts <https://github.com/phenopackets/phenopacket-tools/tree/gh-pages/release_tag/examples/cohorts>`_
+

docs/index.rst

@@ -33,7 +33,7 @@ from our `GitHub repository <https://github.com/phenopackets/phenopacket-tools>`
 The following sections describe phenopacket-tools library and CLI application.
 We start with :ref:`rsttutorial` to provide a quick overview of the CLI functionality.
 We follow with comprehensive description of the :ref:`rstcli`.
-The rest of the documentation offers an in-depth user guide for using the library functionality
+The rest of the documentation offers an in-depth user guide and a showcase of the library functionality
 in JVM-based applications.
 
 .. toctree::
@@ -47,6 +47,7 @@ in JVM-based applications.
    converting
    validation
    examples
+   showcase
 
 
 .. figure:: https://onlinelibrary.wiley.com/cms/asset/1cc0a141-da65-45a3-b7b0-6316b7b02069/ggn2202200016-fig-0002-m.jpg

docs/showcase.rst

@@ -0,0 +1,31 @@
+.. _rstshowcase:
+
+===================================================
+Showcase of applications that use phenopacket-tools
+===================================================
+
+We present a list of tools and applications that use phenopacket-tools to read, build, or Q/C phenopackets.
+
+
+We present a list of tools and applications that use phenopacket-tools to read, build, or Q/C phenopackets and other components of the Phenopacket Schema.
+
+* `LIRICAL <https://www.cell.com/ajhg/fulltext/S0002-9297(20)30230-5>`_ runs phenotype-driven prioritization of Mendelian diseases on a Phenopacket.
+
+   LIRICAL uses `phenopacket-tools-io` to `read phenopackets <https://github.com/TheJacksonLaboratory/LIRICAL/blob/f516e463986880285436fd93540da3c6b7510fb7/lirical-io/src/main/java/org/monarchinitiative/lirical/io/analysis/PhenopacketImportUtil.java#L18>`_.
+
+..
+   TODO
+   and `phenopacket-tools-validator-core` for input `quality control <>`_.
+
+* `SvAnna <https://genomemedicine.biomedcentral.com/articles/10.1186/s13073-022-01046-6>`_ applies phenotype-driven prioritization on coding and regulatory structural variants in long-read genome sequencing.
+
+   SvAnna uses `phenopacket-tools-io` for `reading input <https://github.com/TheJacksonLaboratory/SvAnna/blob/master/svanna-cli/src/main/java/org/monarchinitiative/svanna/cli/cmd/PhenopacketAnalysisDataUtil.java>`_
+   formatted as a phenopacket.
+
+* `HPO Case Annotator <https://github.com/monarch-initiative/HpoCaseAnnotator>`_ is a GUI application for biocuration of case reports, cohorts and families.
+
+   Hpo Case Annotator uses `phenopacket-tools-builder` for `mapping the entered data into Phenopacket Schema <https://github.com/monarch-initiative/HpoCaseAnnotator/tree/development/hpo-case-annotator-export/src/main/java/org/monarchinitiative/hpo_case_annotator/export/ppv2>`_
+   format and `phenopacket-tools-io` for `storing phenopackets <https://github.com/monarch-initiative/HpoCaseAnnotator/blob/509480ff78af3996bdacb6513feedb1f18e39c17/hpo-case-annotator-app/src/main/java/org/monarchinitiative/hpo_case_annotator/app/controller/MainController.java#L727>`_ into JSON files.
+
+
+Please let us know about your application by submitting a request on our `issue tracker <https://github.com/phenopackets/phenopacket-tools/issues>`_.

phenopacket-tools-builder/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>org.phenopackets.phenopackettools</groupId>
         <artifactId>phenopacket-tools</artifactId>
-        <version>1.0.0-RC2</version>
+        <version>1.0.0-RC3</version>
     </parent>
 
     <artifactId>phenopacket-tools-builder</artifactId>

phenopacket-tools-cli/pom.xml

@@ -7,7 +7,7 @@
     <parent>
         <groupId>org.phenopackets.phenopackettools</groupId>
         <artifactId>phenopacket-tools</artifactId>
-        <version>1.0.0-RC2</version>
+        <version>1.0.0-RC3</version>
     </parent>
 
     <artifactId>phenopacket-tools-cli</artifactId>

phenopacket-tools-cli/src/main/java/org/phenopackets/phenopackettools/cli/Main.java

@@ -15,7 +15,7 @@
                 "phenopacket-tools (pxf)",
                 "An application and library for building, conversion, and validation of GA4GH Phenopackets.\n"
         },
-        version = "v1.0.0-RC2",
+        version = "v1.0.0-RC3",
         mixinStandardHelpOptions = true,
         subcommands = {
                 // see https://picocli.info/autocomplete.html
@@ -38,7 +38,7 @@ public class Main {
             .optionParams(italic)
             .build();
 
-    public static final String FOOTER = "\nSee the full documentation at http://phenopackets.org/phenopacket-tools\n";
+    public static final String FOOTER = "\nSee the full documentation at http://phenopackets.org/phenopacket-tools/stable\n";
 
     private Main() {
         // private no-op