NASA PDS Federated API

PDS strives to develop REST-ful web APIs for all online web applications, including data search and DOI management.

This repository is the entry point for the NASA PDS Federated API specifications (e.g. following OpenAPI standard) and their documentation.

Please visit our website at https://nasa-pds.github.io/pds-api/ for user documentation.

Prerequisites

• Python 3

• For PDF generation, basiclatex and accompanying libraries are needed

  brew install basictex
  sudo /Library/TeX/texbin/tlmgr update --self
  sudo /Library/TeX/texbin/tlmgr install latexmk
  sudo /Library/TeX/texbin/tlmgr install tex-gyre
  sudo /Library/TeX/texbin/tlmgr install fncychap
  sudo /Library/TeX/texbin/tlmgr install wrapfig
  sudo /Library/TeX/texbin/tlmgr install capt-of
  sudo /Library/TeX/texbin/tlmgr install framed
  sudo /Library/TeX/texbin/tlmgr install needspace
  sudo /Library/TeX/texbin/tlmgr install tabulary
  sudo /Library/TeX/texbin/tlmgr install varwidth
  sudo /Library/TeX/texbin/tlmgr install titlesec
  

Generate the user's documentation

Set the overall version (e.g. build number) in docs/source/conf.py

The OpenAPI yaml unresolved specifications are stored in the specs directory.

The naming of the specification are: PDS_APIs-{application}-{version}-swagger.yaml

For example: PDS_APIs-registry-1.0.0-swagger.yaml

To add a new specification or a new version of a specification:

1. Copy the OpenAPI Specification under the specs directory following the above filename convention.

2. Add a new entry for this file in docs/source/specifications.rst

3. In the file docs/source/conf.py add a section for the new specification in the redoc object.

4. Generate a PDF of the documentation.

   cd docs/
   make latexpdf
   cp build/latex/pdsapis.pdf build/html/_static
   

5. Generate the Sphinx documentation:

   pip install -e '.[dev]'
   
   sphinx-build -b html docs/source docs/build/html
   

Code of Conduct

All users and developers of the NASA-PDS software are expected to abide by our Code of Conduct. Please read this to ensure you understand the expectations of our community.

Development

To develop this project, use your favorite text editor, or an integrated development environment with Python support, such as PyCharm.

Contributing

For information on how to contribute to NASA-PDS codebases please take a look at our Contributing guidelines.

Documentation

This project uses Sphinx to build its documentation. You can build your projects docs with:

python setup.py build_sphinx

You can access the build files in the following directory relative to the project root:

build/sphinx/html/

The online documentation is auto-generated by the CI/CD process when a new release is tagged.

CI/CD

The template repository comes with our two "standard" CI/CD workflows, stable-cicd and unstable-cicd. The unstable build runs on any push to main (± ignoring changes to specific files) and the stable build runs on push of a release branch of the form release/<release version>. Both of these make use of our GitHub actions build step, Roundup. The unstable-cicd will generate (and constantly update) a SNAPSHOT release. If you haven't done a formal software release you will end up with a v0.0.0-SNAPSHOT release (see NASA-PDS/roundup-action#56 for specifics).