diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index d47c4d48..ff2a334a 100644 --- a/.github/workflows/pages.yml +++ b/.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\\d\\.\\d\\.\\d)(?P-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' }} diff --git a/README.md b/README.md index 7dabba6f..d0b5ef10 100644 --- a/README.md +++ b/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). \ No newline at end of file +Comments, questions or issues? Feel free to submit a ticket to our [GitHub tracker](https://github.com/phenopackets/phenopacket-tools/issues). diff --git a/docs/cli.rst b/docs/cli.rst index af4ae476..12c6bbe4 100644 --- a/docs/cli.rst +++ b/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 `_. 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 `_ 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:: diff --git a/docs/index.rst b/docs/index.rst index d83e40aa..abd116ae 100644 --- a/docs/index.rst +++ b/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 diff --git a/pom.xml b/pom.xml index 38051a77..cd76d995 100644 --- a/pom.xml +++ b/pom.xml @@ -8,8 +8,12 @@ phenopacket-tools 0.4.7 + Phenopacket-tools + An app and library for building, conversion and validation of GA4GH Phenopackets pom + https://phenopackets.org/phenopacket-tools + 3.6.0 @@ -267,11 +271,21 @@ + attach-javadocs jar + + + aggregate + + aggregate + + package + false + diff --git a/sphinx/conf.py~ b/sphinx/conf.py~ deleted file mode 100644 index f065bbd0..00000000 --- a/sphinx/conf.py~ +++ /dev/null @@ -1,41 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -############# -# JR added: -import os -import sys - -sys.path.insert(0, os.path.abspath('../../')) -extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.githubpages', - 'sphinx_rtd_theme', - 'recommonmark' -] -############## - -project = 'phenopacket-tools' -copyright = '2022, Peter Robinson' -author = 'Peter Robinson' - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = [] - -templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - - - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = 'alabaster' -html_static_path = ['_static'] diff --git a/sphinx/index.rst~ b/sphinx/index.rst~ deleted file mode 100644 index 1bff6fd4..00000000 --- a/sphinx/index.rst~ +++ /dev/null @@ -1,20 +0,0 @@ -.. phenopacket-tools documentation master file, created by - sphinx-quickstart on Fri Aug 12 11:03:28 2022. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to phenopacket-tools's documentation! -============================================= - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search`