diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..5bf5d33 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,19 @@ +# This is a comment. +# Each line is a file pattern followed by one or more owners. + +# These owners will be the default owners for everything in +# the repo. Unless a later match takes precedence, +# @global-owner1 and @global-owner2 will be requested for +# review when someone opens a pull request. + +# *************************************************************** +# +# Go to https://github.com/orgs/pds-data-dictionaries/teams to +# find out more information about your applicable team + +* @pds-data-dictionaries/dldd-data-modeling-team + +# ************************************************************** + +# For more information on populating this file, go to +# https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..6973871 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,27 @@ + + +## Summary + +Enter summary here + +## Test Data and/or Report + +Enter info here + +## Related Issues + +Enter related issues here diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 0000000..7a7b248 --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,102 @@ +name: Build and Deploy Docs + +on: + push: + branches: + - 'main' + paths: + - 'docs/**' + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + # Single deploy job since we're just deploying + deploy: + name: 'Build and Deploy Sphinx Docs' + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + if: github.actor != 'pdsen-ci' + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + token: ${{ secrets.ADMIN_GITHUB_TOKEN }} + + - name: Install dependencies + run: | + # Install Sphinx + pip install -r docs/requirements.txt + - name: Make Sphinx + id: make + run: | + cd docs + # Make the HTML docs and copy to main + make github + cd .. + - name: Setup Pages + uses: actions/configure-pages@v2 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + # Upload entire repository + path: '.' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 + + pdfgen: # job 1 + name: 'Build PDF' + runs-on: ubuntu-latest + if: github.actor != 'pdsen-ci' + + steps: + - uses: actions/checkout@v3 + with: + token: ${{ secrets.ADMIN_GITHUB_TOKEN }} + + - name: Set up Python 3 + uses: actions/setup-python@v4 + with: + python-version: '3.7' + + - name: Install dependencies + run: | + # Install Sphinx + pip install -r docs/requirements.txt + # Install dependencies for PDF generation + sudo apt install texlive-latex-recommended texlive-fonts-recommended texlive-latex-extra latexmk + - name: Generate PDF + id: make + run: | + cd docs + make latexpdf + cp build/latex/*.pdf . + - name: Push PDF to Github + run: | + git config --local user.email "pdsen-ci@jpl.nasa.gov" + git config --local user.name "PDSEN CI Bot" + git add -A ./*.pdf + git commit --allow-empty -m "Auto-gen PDF by PDSEN CI Bot" + + - name: Push changes + uses: ad-m/github-push-action@master + with: + github_token: ${{ secrets.ADMIN_GITHUB_TOKEN }} + branch: ${{ github.ref }} + force: true diff --git a/.github/workflows/release-ldd.yml b/.github/workflows/release-ldd.yml new file mode 100644 index 0000000..f53c1f9 --- /dev/null +++ b/.github/workflows/release-ldd.yml @@ -0,0 +1,76 @@ +# This workflow will build a package using Maven and then publish it to GitHub packages when a release is created +# For more information see: https://github.com/actions/setup-java#apache-maven-with-a-settings-path +--- + +name: Release and Tag LDD Release + +on: + push: + branches: + - 'main' + paths: + - 'build/release/**' + +env: + DEPLOY_PATH: ${{ format('{0}/{1}', github.workspace, 'build/release') }} + # TODO - Have to hard-code this for now since Actions don't yet allow the use of env here. + LOGS_PATH: ${{ format('{0}/{1}', github.workspace, 'logs') }} + +jobs: + get_versions: + name: Get Applicable PDS4 Versions + runs-on: ubuntu-latest + if: github.actor != 'pdsen-ci' + outputs: + matrix: ${{ steps.set-matrix.outputs.matrix }} + steps: + - uses: actions/checkout@v3 + with: + token: ${{ secrets.ADMIN_GITHUB_TOKEN }} + ssh-key: ${{ secrets.SSH_KEY }} + + - id: set-matrix + run: | + while read -r line; do + if [[ ! -z "$line" ]]; then + versions=$versions'"'$line'"', + fi + done < $GITHUB_WORKSPACE/pds4_versions.txt + versions="[${versions::-1}]" + echo "{\"pds4_version\":${versions}}" + echo "matrix={\"pds4_version\": $versions}" >> $GITHUB_OUTPUT + + build: # job 1 + name: 'Tag and Release LDD' + needs: get_versions + runs-on: ubuntu-latest + if: github.actor != 'pdsen-ci' + + strategy: + matrix: ${{fromJson(needs.get_versions.outputs.matrix)}} + + steps: + - uses: actions/checkout@v3 + with: + token: ${{ secrets.ADMIN_GITHUB_TOKEN }} + ssh-key: ${{ secrets.SSH_KEY }} + + - name: Set up Python 3 + uses: actions/setup-python@v4 + with: + python-version: '3.7' + + - name: Adding dependencies + run: | + sudo apt-get update && sudo apt-get install -y libxml2-dev libxslt1-dev python3-libxml2 + + - name: Clean previous dev/snapshot tags + run: | + git fetch --prune --unshallow --tags + git tag -l | grep 'dev' | xargs -t -I arg sh -c 'git tag -d arg;git push --delete origin arg;' + + - name: Publish new release + run: | + pip install pds-github-util + ldd-release --ingest_ldd_src_dir ${{github.workspace}}/src --ldd_output_path ${{ env.DEPLOY_PATH }} --token ${{ secrets.GITHUB_TOKEN }} --pds4_version ${{matrix.pds4_version}} + diff --git a/.github/workflows/submod-ci.yml b/.github/workflows/submod-ci.yml new file mode 100644 index 0000000..da8d355 --- /dev/null +++ b/.github/workflows/submod-ci.yml @@ -0,0 +1,212 @@ +# This workflow will build a package using Maven and then publish it to GitHub packages when a release is created +# For more information see: https://github.com/actions/setup-java#apache-maven-with-a-settings-path +--- +name: PDS4 LDD Automation +on: + push: + branches: + - '**' + - '!main' + - '!gh-pages' + paths: + - src/** + - .github/** + - pds4_versions.txt + workflow_dispatch: + +env: + REGRESSION_TEST_PATH: ${{ format('{0}/{1}/', github.workspace, 'test') }} + # TODO - Have to hard-code this for now since Actions don't yet allow the use of env here. + LOGS_PATH: ${{ format('{0}/{1}', github.workspace, 'logs') }} + DEPLOY_PATH: ${{ format('{0}/{1}/{2}/{3}', github.workspace, 'build', 'development', github.sha) }} + +jobs: + get_versions: + name: Get PDS4 Versions + runs-on: ubuntu-latest + if: github.actor != 'pdsen-ci' + outputs: + matrix: ${{ steps.set-matrix.outputs.matrix }} + steps: + - uses: actions/checkout@v3 + with: + token: ${{ secrets.ADMIN_GITHUB_TOKEN }} + ssh-key: ${{ secrets.SSH_KEY }} + + - id: set-matrix + run: | + # Look through lines and pull out the versions + while read -r line; do + if [[ ! -z "$line" ]]; then + versions=$versions'"'$line'"', + fi + done < pds4_versions.txt + versions="[${versions::-1}]" + echo "{\"pds4_version\":${versions}}" + + # Baseline: Set pds4 version to versions from file + echo "matrix={\"pds4_version\": $versions}" >> $GITHUB_OUTPUT + + build: + name: 'Generate and Validate' + needs: get_versions + runs-on: ubuntu-latest + if: github.actor != 'pdsen-ci' + + strategy: + matrix: ${{fromJson(needs.get_versions.outputs.matrix)}} + + steps: + - uses: actions/checkout@v3 + with: + token: ${{ secrets.ADMIN_GITHUB_TOKEN }} + ssh-key: ${{ secrets.SSH_KEY }} + + - name: Set up Python 3 + uses: actions/setup-python@v4 + with: + python-version: '3.9' + + - name: Update submodules for dependencies + run: | + git submodule update --init --force --remote + + - name: Generate LDDs + id: generate + uses: NASA-PDS/sumo-gen-action@main + with: + data_path: ${{ format('{0}/{1}', env.DEPLOY_PATH, matrix.pds4_version) }} + pds4_im_version: ${{ matrix.pds4_version }} + pds4_development_release: ${{ matrix.pds4_development_release }} + lddtool_development_release: ${{ matrix.lddtool_development_release }} + test_path: ${{ env.REGRESSION_TEST_PATH }} + logs_path: ${{ env.LOGS_PATH }} + token: ${{ secrets.ADMIN_GITHUB_TOKEN }} + + - name: Check logs + run: | + ls -R ${{ env.LOGS_PATH }} + + - name: Upload LDDs to Github Action Artifacts + uses: actions/upload-artifact@v3 + with: + name: v${{matrix.pds4_version}}_LDDs + path: ${{ env.DEPLOY_PATH }} + if: ${{ always() }} + + - name: Upload Logs to Github Action Artifacts + uses: actions/upload-artifact@v3 + with: + name: v${{matrix.pds4_version}}_execution_logs + path: ${{ env.LOGS_PATH }} + if: ${{ always() }} + + upload_logs_only: # job 3 + name: 'Add Run Logs to Github' + runs-on: ubuntu-latest + needs: build + if: ${{ failure() && github.actor != 'pdsen-ci' }} + + steps: + - uses: actions/checkout@v3 + with: + token: ${{ secrets.ADMIN_GITHUB_TOKEN }} + ssh-key: ${{ secrets.SSH_KEY }} + + - uses: actions/download-artifact@v3 + with: + path: /tmp/artifacts + + - name: Display structure of downloaded files + run: ls -R /tmp/artifacts + + - name: Clean out old logs + run: | + path=$(dirname ${{ env.LOGS_PATH }}) + rm -fr $path/* + + - name: Move the execution logs to their new home + run: | + rm -fr ${{ env.LOGS_PATH }} + mkdir -p ${{ env.LOGS_PATH }} + cp -R /tmp/artifacts/*logs ${{ env.LOGS_PATH }}/ + + - name: Display structure of downloaded files + run: ls -R ${{ env.LOGS_PATH }} + + - name: Push logs to Github + run: | + git config --local user.email "pdsen-ci@jpl.nasa.gov" + git config --local user.name "PDSEN CI Bot" + git add -A ${{ env.LOGS_PATH }} + git commit -m "Add logs from failed SuMo generation" + git push origin HEAD + + + upload_all: # job 3 + name: 'Add LDDs and Logs to Github' + runs-on: ubuntu-latest + needs: build + if: ${{ github.actor != 'pdsen-ci' }} + + steps: + - uses: actions/checkout@v3 + with: + token: ${{ secrets.ADMIN_GITHUB_TOKEN }} + ssh-key: ${{ secrets.SSH_KEY }} + + - uses: actions/download-artifact@v3 + with: + path: /tmp/artifacts + + - name: Display structure of downloaded files + run: | + ls -R /tmp/artifacts + + - name: Clean previous dev/snapshot tags + run: | + git fetch --prune --unshallow --tags + git tag -l | grep 'dev' | xargs -t -I arg sh -c 'git tag -d arg;git push --delete origin arg;' + + - name: Clean out old LDDs and logs + run: | + path=$(dirname ${{ env.DEPLOY_PATH }}) + rm -fr $path/* + + path=${{ env.LOGS_PATH }} + rm -fr $path/* + + - name: Move the LDDs to their new home + run: | + mkdir -p ${{ env.DEPLOY_PATH }} + ls -R /tmp/artifacts/*LDDs/* + rsync -av /tmp/artifacts/*LDDs/* ${{ env.DEPLOY_PATH }} + + - name: Display structure of downloaded files + run: ls -R ${{ env.DEPLOY_PATH }} + + - name: If Release Branch, move to release dir + shell: bash + run: | + if [[ "${{github.ref}}" == *"release"* ]]; then + rsync -av /tmp/artifacts/*LDDs/* ${{github.workspace}}/build/release/ + ls -R ${{github.workspace}}/build/release/ + fi + + - name: Move the execution logs to their new home + run: | + rm -fr ${{ env.LOGS_PATH }} + mkdir -p ${{ env.LOGS_PATH }} + rsync -av /tmp/artifacts/*logs ${{ env.LOGS_PATH }}/ + + - name: Display structure of downloaded files + run: ls -R ${{ env.LOGS_PATH }} + + - name: Push LDDs and Logs to Github + run: | + git config --local user.email "pdsen-ci@jpl.nasa.gov" + git config --local user.name "PDSEN CI Bot" + git add -A $(dirname ${{ env.DEPLOY_PATH }}) ${{ env.LOGS_PATH }} ${{github.workspace}}/build/release/ + git commit -m "Auto-generated LDDs by PDSEN CI Bot" + git push origin HEAD + diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b615ac5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,48 @@ +# Object files +*.o +*.pkl +*.pyc + +# Libraries +*.lib +*.a + +# Eclipse files +.settings/ +*.project +*.classpath + +# IntelliJ files +.idea/ +*.iml + +# Shared objects (inc. Windows DLLs) +*.dll +*.so +*.so.* +*.dylib + +# Executables +*.exe +*.out +*.app + +# Temporary files +*~ +src/test/temp/ + +# other stuff +*.xpr +*.swp +.*.swp +*.sublime-* +*.DS_Store +pom.xml.versionsBackup + +# Java stuff +*.javac +.gwt/ +target/ + +# Sphinx stuff +docs/build/ diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md new file mode 100644 index 0000000..d8f60dd --- /dev/null +++ b/README.md @@ -0,0 +1,190 @@ + + +# {dictionary name} ({prefix:}) {"Discipline" or "Local"} Dictionary + + +The {dictionary name} dictionary provides classes and attributes for +{brief functional description} + +### Steward +{steward name} ({steward GitHub handle}), {steward node} + + +# Documentation + + +The User's Guide and detailed documentation for using this dictionary in +label design and processing +are located at https://pds-data-dictionaries.github.io/{repo id}. + + +# Latest Release + + +* Download dictionary files from the [PDS Data Dictionaries Page](https://pds.nasa.gov/datastandards/dictionaries/#{dictionary prefix}) +* On [GitHub](../../releases/latest) +* Review the [Change log]({change log file name}) + +# About This Repository + +In this repo you will find... +* **[src](src)/** - The directory containing the managed *IngestLDD* file + that defines this namespace. This is where changes to the namespace + itself are made. +* **[build](build)/** - This directory holds the files generated by the +build processing, including the schema files used in designing and +validating labels, JSON for inclusion in code, and report files from the +LDDTool execution that created the files. There are separate +subdirectories for development versions and releases. +* **[test](test)/** - This directory contains regression tests (in the + form of documented labels) for this namespace. +* **[logs](logs)/** - This directory contains the logs generated by the + GitHub-automated build and test processes of LDDTool and Validate. +* **[examples](examples)/** - This directory contains label samples for +using this namespace. +* **[.github](.github)/** - This (possibly hidden) directory contains +internal files used to manage the automated build processes. + + +The `main` branch is where you should merge your final changes to documentation and LDD structure. +The `gh-pages` branch is auto-generated and used to run the documentation site. **DO NOT MAKE CHANGES HERE**. + +# Contributing to this Dictionary + +## Suggest a Feature or Report a Bug + + +There is a common place to request enhancements and report problems for +any PDS-curated dictionary - the [PDS4 Issue Repo](https://github.com/pds-data-dictionaries/PDS4-LDD-Issue-Repo/issues/new/choose). +Search for the \[{repo id}\] update request block and click the green +"Get Started" button. + +## Contribute Code or documentation +If you'd like to actively contribute to development, begin with the +feature/bug process described above. Then familiarize yourself with +the [LDD Update Process](https://pds-data-dictionaries.github.io/development/ldd-update.html) +and contact the dictionary steward to coordinate development, testing, +and release. And thanks! + +# General Support for Dictionary Developers +See the [PDS Data Dictionaries pages](https://pds-data-dictionaries.github.io) +for documentation and tutorials describing the procedures +required to reserve a namespace, +establish a new repo, and build your dictionary. + + +If you need help creating your *IngestLDD* file, contact the [Dictionary Stewards Group](https://pds-data-dictionaries.github.io/teams/pds-dd-stewards.html). Documentation is in preparation. + +# For Dictionary Stewards + +See the [tutorial on updating and building an IngestLDD](https://pds-data-dictionaries.github.io/support/tutorials.html#ldd-update-and-build-tutorial) and the [LDD Update Process](https://pds-data-dictionaries.github.io/development/ldd-update.html) for documentation of those procedures. + +## Building the dictionary + +Each build is auto-generated using Github Actions, PDS4 LDDTool, and Validate Tool. + +You can also download the *IngestLDD* file and build the dictionary locally. +You will need to install *[LDDTool]* (https://nasa-pds.github.io/pds4-information-model/model-lddtool/index.html) on your system. Once you do, +you can manually run [LDDTool](https://nasa-pds.github.io/pds4-information-model/model-lddtool/index.html) on the IngestLDD using the following command: + +``` +lddtool -lpsnJ {IngestLDD file name}.xml +``` + +# Generating Namespace Documentation +The documentation website is managed by GitHub Pages. When changes are made on the `main` branch, GitHub will process those changes and update the `gh-pages` branch, which drives the website on pds-data-dictionaries.github.io. + +If you would like to test your changes and generate the site on your own system: + +1. Clone the repository +2. Install Python dependencies (preferably within a Python virtual environment[^1]) using this command: +``` +pip install -r requirements.txt +``` +3. Follow steps below + +[^1]: [Python Virtual Environment How-To at docs.python.org](https://docs.python.org/3/library/venv.html) + +## To Generate HTML + +1. Build the HTML documents +``` +cd docs +make clean html +``` + Note that in Windows environments you will need to run the "clean" and "html" operations as separate invocations of "make": +``` +cd docs +make clean +make html +```` + +2. Preview the HTML in your browser +``` +open build/html/index.html +``` + +## To Generate PDF + +1. Install some additional dependencies: + + On a Mac: + ``` + brew install texlive + ``` + + On Linux: + ``` + apt-get install texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended + ``` + +2. Make the PDF +``` +cd docs +make latexpdf +``` + +The output PDF will be written into the *docs/* directory. +The output file name will depend on the value for the ```project``` variable +in the *docs/source/conf.py* file. diff --git a/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.JSON b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.JSON new file mode 100644 index 0000000..db8e82f --- /dev/null +++ b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.JSON @@ -0,0 +1,72 @@ +[ + { + "dataDictionary": { + "Title": "PDS4 Data Dictionary" , + "IM Version": "1.19.0.0" , + "LDD Version": "1.0.0.0" , + "Date": "2023-03-18T11:12:42" , + "Description": "This document is a dump of the contents of the PDS4 Data Dictionary" , + "namespaces": ["pds:", "example:"] , + "classDictionary": [ + { + "class": { + "identifier": "0001_NASA_PDS_1.example.My_First_LDD" , + "title": "My_First_LDD" , + "registrationAuthorityId": "0001_NASA_PDS_1" , + "nameSpaceId": "example" , + "steward": "janedoe" , + "versionId": "1.0.0.0" , + "isAbstract": "false" , + "isDeprecated": "false" , + "description": "My first class" + , "associationList": [ + {"association": { + "identifier": "0001_NASA_PDS_1.example.My_First_LDD.example.my_first_attribute" , + "title": "my_first_attribute" , + "assocType": "attribute_of" , + "isAttribute": "true" , + "isChoice": "false" , + "isAny": "false" , + "groupName": "null" , + "minimumCardinality": "1" , + "maximumCardinality": "1" , + "classOrder": "1010" , + "attributeId": [ + "0001_NASA_PDS_1.example.My_First_LDD.example.my_first_attribute" + ] + } + } + ] + } + } + ] + , "attributeDictionary": [ + { + "attribute": { + "identifier": "0001_NASA_PDS_1.example.My_First_LDD.example.my_first_attribute" , + "title": "my_first_attribute" , + "registrationAuthorityId": "0001_NASA_PDS_1" , + "nameSpaceId": "example" , + "steward": "janedoe" , + "versionId": "1.19" , + "description": "My first attribute " , + "isNillable": "false" , + "isEnumerated": "false" , + "isDeprecated": "false" , + "dataType": "ASCII_Integer" , + "dataTypeId": "0001_NASA_PDS_1.pds.ASCII_Integer" , + "minimumCharacters": "Unbounded" , + "maximumCharacters": "Unbounded" , + "minimumValue": "-9223372036854775808" , + "maximumValue": "9223372036854775807" , + "pattern": "null" , + "unitOfMeasure": "null" , + "unitOfMeasureId": "null" , + "unitId": "null" , + "defaultUnitId": "null" + } + } + ] + } + } +] diff --git a/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.csv b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.csv new file mode 100644 index 0000000..e07ef99 --- /dev/null +++ b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.csv @@ -0,0 +1,3 @@ +"Sort Key","Type","Name","Version","Name Space Id","Description","Steward","Value Type","Minimum Cardinality","Maximum Cardinality","Minimum Value","Maximum Value","Minimum Characters","Maximum Characters","Unit of Measure Type","Specified Unit Id","Attribute Concept","Conceptual Domain" +"example:My_First_LDD:1 ","Class","My_First_LDD","1.0.0.0","example","My first class","janedoe","","","","","","","","","","","" +"example:My_First_LDD:2 example:my_first_attribute:1 ","Attribute","my_first_attribute","n/a","example","My first attribute ","janedoe","ASCII_Integer","1","1","-9223372036854775808","9223372036854775807","Unbounded","Unbounded","Units_of_None","none","TBD_classConcept","INTEGER" diff --git a/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.sch b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.sch new file mode 100644 index 0000000..42f27c9 --- /dev/null +++ b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.sch @@ -0,0 +1,21 @@ + + + + + + + Schematron using XPath 2.0 + + + + + + + + + + + + + + diff --git a/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.txt b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.txt new file mode 100644 index 0000000..0205188 --- /dev/null +++ b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.txt @@ -0,0 +1,73 @@ +PDS4 Local Data Dictionary Processing Report + +Configuration: + LDDTool Version 14.1.2 + LDD Version Id: 1.0.0.0 + LDD Label Version Id: 1.25 + LDD Discipline (T/F): true + LDD Namespace URL: http://pds.nasa.gov/pds4/ + LDD URN Prefix: urn:nasa:pds: + Time Sat Mar 18 18:12:41 UTC 2023 + Common Schema [PDS4_PDS_1J00.xsd] + Common Schematron [PDS4_PDS_1J00.sch] + IM Version Id: 1.19.0.0 + IM Namespace Id: pds + IM Label Version Id: 1.25 + IM Object Model [UpperModel.pont] + IM Data Dictionary [dd11179.pins] + IM Configuration File [MDPTNConfigClassDisp.xml] + IM Glossary [Glossary.pins] + IM Document Spec [DMDocument.pins] + +Parameters: + Input File [/home/runner/work/ldd-template/ldd-template/src/PDS4_EXAMPLE_IngestLDD.xml] + PDS Processing true + LDD Processing true + Discipline LDD true + Mission LDD false + Write Attr Elements false + Merge with Master false + +Summary: + Classes 1 + Attributes 1 + Associations 1 + Error messages 0 + Warning messages 0 + Information messages 0 + +Detailed validation messages + +Parsed Input - Header: + LDD Name Example LDD + LDD Version 1.0.0.0 + Full Name Doe, Jane + Steward janedoe + Namespace Id example + Comment _TBD_Ingest_LDD + Last Modification Time 2030-04-10T18:00:00Z + PDS4 Merge Flag false + +Parsed Input - Attributes: + + name my_first_attribute + version 1.19 + value data type ASCII_Integer + description My first attribute + +Parsed Input - Classes: + + name My_First_LDD + description My first class + is abstract false + is choice false + subclass of USER + + Associations + + local identifier my_first_attribute + minimum occurrences 1 + maximum occurrences 1 + reference type attribute_of + +End of Report diff --git a/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.xml b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.xml new file mode 100644 index 0000000..13419b6 --- /dev/null +++ b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.xml @@ -0,0 +1,54 @@ + + + + + + + + urn:nasa:pds:system_bundle:xml_schema:example-xml_schema_1.19.0.0_1.0.0.0 + 1.25 + PDS4 XML Schema - EXAMPLE V1.0.0.0 + 1.19.0.0 + Product_XML_Schema + + + 2023-03-18 + 1.25 + This is the system generated PDS4 product label for PDS4 XML Schema and Schematron files. + + + + + + PDS4_EXAMPLE_1J00_1000.xsd + 2023-03-18T11:12:42 + 2400 + 54 + + + PDS4_EXAMPLE_1J00_1000.xsd + 0 + XML Schema Version 1.1 + This is a PDS4 XML Schema file for the declared namespace. + + + + + PDS4_EXAMPLE_1J00_1000.sch + 2023-03-18T11:12:42 + 1169 + 21 + + + PDS4_EXAMPLE_1J00_1000.sch + 0 + Schematron ISO/IEC 19757-3:2006 + This is the PDS4 Schematron file for the declared namespace. Schematron provides rule-based validation for XML Schema. + + + diff --git a/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.xsd b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.xsd new file mode 100644 index 0000000..1360e6e --- /dev/null +++ b/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.xsd @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + +_TBD_Ingest_LDD + + + + + + + +My first class + + + + + + + + This section contains the simpleTypes that provide more constraints + than those at the base data type level. The simpleTypes defined here build on the base data + types. This is another component of the common dictionary and therefore falls within the + common namespace. + + + + + +My first attribute + + + + + + + diff --git a/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.JSON b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.JSON new file mode 100644 index 0000000..484ecaa --- /dev/null +++ b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.JSON @@ -0,0 +1,72 @@ +[ + { + "dataDictionary": { + "Title": "PDS4 Data Dictionary" , + "IM Version": "1.18.0.0" , + "LDD Version": "1.0.0.0" , + "Date": "2023-01-20T06:37:53" , + "Description": "This document is a dump of the contents of the PDS4 Data Dictionary" , + "namespaces": ["pds:", "example:"] , + "classDictionary": [ + { + "class": { + "identifier": "0001_NASA_PDS_1.example.My_First_LDD" , + "title": "My_First_LDD" , + "registrationAuthorityId": "0001_NASA_PDS_1" , + "nameSpaceId": "example" , + "steward": "janedoe" , + "versionId": "1.0.0.0" , + "isAbstract": "false" , + "isDeprecated": "false" , + "description": "My first class" + , "associationList": [ + {"association": { + "identifier": "0001_NASA_PDS_1.example.My_First_LDD.example.my_first_attribute" , + "title": "my_first_attribute" , + "assocType": "attribute_of" , + "isAttribute": "true" , + "isChoice": "false" , + "isAny": "false" , + "groupName": "null" , + "minimumCardinality": "1" , + "maximumCardinality": "1" , + "classOrder": "1010" , + "attributeId": [ + "0001_NASA_PDS_1.example.My_First_LDD.example.my_first_attribute" + ] + } + } + ] + } + } + ] + , "attributeDictionary": [ + { + "attribute": { + "identifier": "0001_NASA_PDS_1.example.My_First_LDD.example.my_first_attribute" , + "title": "my_first_attribute" , + "registrationAuthorityId": "0001_NASA_PDS_1" , + "nameSpaceId": "example" , + "steward": "janedoe" , + "versionId": "1.18" , + "description": "My first attribute " , + "isNillable": "false" , + "isEnumerated": "false" , + "isDeprecated": "false" , + "dataType": "ASCII_Integer" , + "dataTypeId": "0001_NASA_PDS_1.pds.ASCII_Integer" , + "minimumCharacters": "Unbounded" , + "maximumCharacters": "Unbounded" , + "minimumValue": "-9223372036854775808" , + "maximumValue": "9223372036854775807" , + "pattern": "null" , + "unitOfMeasure": "null" , + "unitOfMeasureId": "null" , + "unitId": "null" , + "defaultUnitId": "null" + } + } + ] + } + } +] diff --git a/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.csv b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.csv new file mode 100644 index 0000000..e07ef99 --- /dev/null +++ b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.csv @@ -0,0 +1,3 @@ +"Sort Key","Type","Name","Version","Name Space Id","Description","Steward","Value Type","Minimum Cardinality","Maximum Cardinality","Minimum Value","Maximum Value","Minimum Characters","Maximum Characters","Unit of Measure Type","Specified Unit Id","Attribute Concept","Conceptual Domain" +"example:My_First_LDD:1 ","Class","My_First_LDD","1.0.0.0","example","My first class","janedoe","","","","","","","","","","","" +"example:My_First_LDD:2 example:my_first_attribute:1 ","Attribute","my_first_attribute","n/a","example","My first attribute ","janedoe","ASCII_Integer","1","1","-9223372036854775808","9223372036854775807","Unbounded","Unbounded","Units_of_None","none","TBD_classConcept","INTEGER" diff --git a/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.sch b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.sch new file mode 100644 index 0000000..0407ef9 --- /dev/null +++ b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.sch @@ -0,0 +1,21 @@ + + + + + + + Schematron using XPath 2.0 + + + + + + + + + + + + + + diff --git a/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.txt b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.txt new file mode 100644 index 0000000..889b80f --- /dev/null +++ b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.txt @@ -0,0 +1,73 @@ +PDS4 Local Data Dictionary Processing Report + +Configuration: + LDDTool Version 14.1.2 + LDD Version Id: 1.0.0.0 + LDD Label Version Id: 1.24 + LDD Discipline (T/F): true + LDD Namespace URL: http://pds.nasa.gov/pds4/ + LDD URN Prefix: urn:nasa:pds: + Time Fri Jan 20 14:37:52 UTC 2023 + Common Schema [PDS4_PDS_1I00.xsd] + Common Schematron [PDS4_PDS_1I00.sch] + IM Version Id: 1.18.0.0 + IM Namespace Id: pds + IM Label Version Id: 1.24 + IM Object Model [UpperModel.pont] + IM Data Dictionary [dd11179.pins] + IM Configuration File [MDPTNConfigClassDisp.xml] + IM Glossary [Glossary.pins] + IM Document Spec [DMDocument.pins] + +Parameters: + Input File [/home/runner/work/ldd-template/ldd-template/src/PDS4_EXAMPLE_IngestLDD.xml] + PDS Processing true + LDD Processing true + Discipline LDD true + Mission LDD false + Write Attr Elements false + Merge with Master false + +Summary: + Classes 1 + Attributes 1 + Associations 1 + Error messages 0 + Warning messages 0 + Information messages 0 + +Detailed validation messages + +Parsed Input - Header: + LDD Name Example LDD + LDD Version 1.0.0.0 + Full Name Doe, Jane + Steward janedoe + Namespace Id example + Comment _TBD_Ingest_LDD + Last Modification Time 2030-04-10T18:00:00Z + PDS4 Merge Flag false + +Parsed Input - Attributes: + + name my_first_attribute + version 1.18 + value data type ASCII_Integer + description My first attribute + +Parsed Input - Classes: + + name My_First_LDD + description My first class + is abstract false + is choice false + subclass of USER + + Associations + + local identifier my_first_attribute + minimum occurrences 1 + maximum occurrences 1 + reference type attribute_of + +End of Report diff --git a/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.xml b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.xml new file mode 100644 index 0000000..3ac3f57 --- /dev/null +++ b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.xml @@ -0,0 +1,54 @@ + + + + + + + + urn:nasa:pds:system_bundle:xml_schema:example-xml_schema_1.18.0.0_1.0.0.0 + 1.24 + PDS4 XML Schema - EXAMPLE V1.0.0.0 + 1.18.0.0 + Product_XML_Schema + + + 2023-01-20 + 1.24 + This is the system generated PDS4 product label for PDS4 XML Schema and Schematron files. + + + + + + PDS4_EXAMPLE_1I00_1000.xsd + 2023-01-20T06:37:53 + 2400 + 54 + + + PDS4_EXAMPLE_1I00_1000.xsd + 0 + XML Schema Version 1.1 + This is a PDS4 XML Schema file for the declared namespace. + + + + + PDS4_EXAMPLE_1I00_1000.sch + 2023-01-20T06:37:53 + 1169 + 21 + + + PDS4_EXAMPLE_1I00_1000.sch + 0 + Schematron ISO/IEC 19757-3:2006 + This is the PDS4 Schematron file for the declared namespace. Schematron provides rule-based validation for XML Schema. + + + diff --git a/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.xsd b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.xsd new file mode 100644 index 0000000..07bf4f7 --- /dev/null +++ b/build/release/1.18.0.0/PDS4_EXAMPLE_1I00_1000.xsd @@ -0,0 +1,54 @@ + + + + + + + + + + + + + + + +_TBD_Ingest_LDD + + + + + + + +My first class + + + + + + + + This section contains the simpleTypes that provide more constraints + than those at the base data type level. The simpleTypes defined here build on the base data + types. This is another component of the common dictionary and therefore falls within the + common namespace. + + + + + +My first attribute + + + + + + + diff --git a/build/release/README.md b/build/release/README.md new file mode 100644 index 0000000..3b21f0b --- /dev/null +++ b/build/release/README.md @@ -0,0 +1 @@ +Contains the released LDDs auto-generated by GitHub Actions. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..05f921e --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,38 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +github: + @make clean checklinks html + @find .. -mindepth 1 -maxdepth 1 -type d -not -name "*git*" -not -name "*docs" -exec rm -fr {} \; + @cp -a build/html/. .. + +cleaner: + @make clean + @find .. -mindepth 1 -maxdepth 1 -type d -not -name "*git*" -not -name "*docs" -exec rm -fr {} \; + +.PHONY: help Makefile checklinks + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +# LINKCHECKDIR = build/linkcheck + +# .PHONY: checklinks +# checklinks: +# $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(LINKCHECKDIR) +# @echo +# @echo "Check finished. Report is in $(LINKCHECKDIR)." diff --git a/docs/examplenamespace.pdf b/docs/examplenamespace.pdf new file mode 100644 index 0000000..be8fe99 Binary files /dev/null and b/docs/examplenamespace.pdf differ diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..daa99ba --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +sphinx==4.5.0 +sphinx-rtd-theme==1.0.0 +gitpython==3.1.30 +sphinxemoji==0.2.0 +myst-parser==0.17.2 diff --git a/docs/source/_static/images/PDS_Planets.png b/docs/source/_static/images/PDS_Planets.png new file mode 100644 index 0000000..887eef4 Binary files /dev/null and b/docs/source/_static/images/PDS_Planets.png differ diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css new file mode 100644 index 0000000..e0173bd --- /dev/null +++ b/docs/source/_static/theme_overrides.css @@ -0,0 +1,28 @@ +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + .wy-table-responsive table td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + .wy-table-responsive { + overflow: visible !important; + } +} + +/* replace the copyright to eliminate the copyright symbol enforced by + the ReadTheDocs theme but eschewed by our legal team */ +div[role=contentinfo] { + visibility: hidden; + position: relative; +} + +div[role=contentinfo]:after { + visibility: visible; + position: absolute; + top: 0; + left: 0; + content: "This is a work of the U.S. Government and is not subject to copyright pursuant to 17 USC 105."; +} diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..d356628 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,100 @@ +# 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 = 'Example Namespace' +# copyright = overidden by CSS specified below +author = 'NASA Planetary Data System' + + +# -- 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.ext.autosectionlabel', + 'sphinx_rtd_theme', + 'sphinxemoji.sphinxemoji', + 'myst_parser' +] + +# 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' + +html_context = { + 'display_github': True, + "github_user": "pds-data-dictionaries", + "github_repo": "ldd-template", + "github_version": "main/docs/source/" +} + +html_css_files = [ + 'theme_overrides.css', +] + +html_theme_options = { + 'canonical_url': '', + 'logo_only': False, + 'display_version': True, + 'prev_next_buttons_location': 'bottom', + 'style_external_links': False, + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': False +} + +myst_enable_extensions = [ + "deflist", + "fieldlist" +] + +latex_elements = { + 'maxlistdepth': '10' +} \ No newline at end of file diff --git a/docs/source/detailed/example.md b/docs/source/detailed/example.md new file mode 100644 index 0000000..9bfb007 --- /dev/null +++ b/docs/source/detailed/example.md @@ -0,0 +1,21 @@ +# <My_First_LDD> +**REQUIRED** + +Submitter: Jane Doe + +My first class + +## <my_first_attribute> +**REQUIRED** + +Submitter: Jane Doe + +My first attribute + +### Subheader 3 + +More details + +#### Subheader 4 + +More Details diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..d446531 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,23 @@ +.. PDS Local Data Dictionaries documentation master file, created by + sphinx-quickstart on Thu Jul 2 18:01:19 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Example Namespace Documentation +=================================== + +.. include:: intro.md + + +.. toctree:: + :maxdepth: 3 + :caption: User Guide + + user/user-guide + + +.. toctree:: + :maxdepth: 3 + :caption: Detailed Documentation + + detailed/example diff --git a/docs/source/intro.md b/docs/source/intro.md new file mode 100644 index 0000000..327a725 --- /dev/null +++ b/docs/source/intro.md @@ -0,0 +1 @@ +Short abstract for the namespace should go here diff --git a/docs/source/user/user-guide.md b/docs/source/user/user-guide.md new file mode 100644 index 0000000..40030cb --- /dev/null +++ b/docs/source/user/user-guide.md @@ -0,0 +1,75 @@ +{date} +{author} + +> Note to authors who use this outline: The outline is a +> suggestion only. It includes the minimum of content needed to inform the +> dictionary user. Authors are expected to tailor the outline to their particular +> purposes, elaborating and providing context as needed. + +# Introduction + 1. Purpose of this User’s Guide + 1. Audience + 1. Applicable Documents + +# Overview of the {name} Local Data Dictionary + +*What is this dictionary for? What kinds of products might +use this dictionary? Who is the steward of this dictionary (person and node +name)? How often is it updated? To whom should questions about it be directed? +(Give an email address or link to a page with contact information.)* + +# Organization of Classes and Attributes + +*Give a schematic diagram or a list showing the hierarchy of +classes in order of appearance in label. Refer the reader to the Definitions +section for complete definitions. An example of such a list is given on the +page [Filling Out The Spectral Dictionary Classes](http://sbndev.astro.umd.edu/wiki/Filling_Out_the_Spectral_Dictionary_Classes#.3CCircular_FOV.3E) +on the PDS Small Bodies Node wiki. In this example the names of classes and attributes have hyperlinks to +their definitions further down the page, a useful lookup tool.* + +*The author should take into consideration the complexity +of the dictionary when organizing this section.  If the hierarchy is large or +complicated, it may be helpful to break it down by class as shown in the +following subsections, but don’t forget to provide a high-level view of how the +classes relate to one another.* + +## Class 1 + +*What is this class for?* + +*Give a schematic diagram or a list of the attributes in this class in order of +appearance in label. Refer reader to Definitions section for complete definitions.* + +*Give label snippets showing use of the class and attributes, with annotations +as appropriate. Refer reader to Examples section for complete examples.* + +*Explain why some things are required and others are optional.* + +*List and explain any rules that apply to this class (e.g. from Schematron).* + +## Class 2 + +[repeat this subsection for each class] + +# Definitions + +*Give an alphabetical list of all classes and attributes +with complete definitions. (Useful ones, not silly ones like "The +map_projection_name attribute provides the name of the map projection.")* + +*Include:* + +- *Class or attribute name (indicate which it is; capitalize class names according to PDS4 standard)* +- *PDS4 data type (ASCII_Short_String_Collapsed, ASCII_Real, ASCII_Date, etc.)* +- *Definition in complete sentences* +- *Cardinality (minimum and maximum number of values permitted)* +- *Nillable, yes or no? Explain when it is appropriate to use a nil value* +- *Minimum and maximum numeric values, if applicable* +- *Minimum and maximum number of characters, if applicable* +- *List of valid values, if applicable.* + +# Examples + +*Give one or more examples of label snippets for real products, annotated as appropriate. +Make sure the examples can be successfully validated using the latest version of the PDS4 +core dictionary and, of course, the dictionary described in this document.* diff --git a/logs/v1.19.0.0_execution_logs/lddtool_run_log_20230318181240.txt b/logs/v1.19.0.0_execution_logs/lddtool_run_log_20230318181240.txt new file mode 100644 index 0000000..e289eb3 --- /dev/null +++ b/logs/v1.19.0.0_execution_logs/lddtool_run_log_20230318181240.txt @@ -0,0 +1,36 @@ + +>> INFO LDDTOOL Version: 14.1.2 +>> INFO IM Version Id: 1.19.0.0 +>> INFO IM Namespace Id: pds +>> INFO IM Label Version Id: 1.25 +>> INFO Date: Sat Mar 18 18:12:41 UTC 2023 +>> INFO PARENT_DIR: /tmp/lddtool-14.1.2 +>> INFO SCRIPT_DIR: /tmp/lddtool-14.1.2/bin +>> INFO LIB_DIR: /tmp/lddtool-14.1.2/lib + +>>> INFO Init: - Config.Properties Namespace Id Using:pds +>>> INFO Init: - LDD Dictionary_Type is Discipline +>>> WARNING Init: - Config.Properties Namespace Id Not Found:example + + -- LDDTool Execution Summary -- + 1 warning(s) + 0 error(s) + 0 fatal error(s) + +Input: + + - IM Version: 1J00 + - PDS4 Flag: true + - LDD Flag: true + - Export JSON Flag: true + + - Ingest LDD(s): /home/runner/work/ldd-template/ldd-template/src/PDS4_EXAMPLE_IngestLDD.xml + +Output: + + - ./PDS4_EXAMPLE_1J00_1000.xsd + - ./PDS4_EXAMPLE_1J00_1000.sch + - ./PDS4_EXAMPLE_1J00_1000.xml + - ./PDS4_EXAMPLE_1J00_1000.JSON + +>> INFO Exit(0) diff --git a/logs/v1.19.0.0_execution_logs/validate_report_20230318181247.txt b/logs/v1.19.0.0_execution_logs/validate_report_20230318181247.txt new file mode 100644 index 0000000..8ed5e81 --- /dev/null +++ b/logs/v1.19.0.0_execution_logs/validate_report_20230318181247.txt @@ -0,0 +1,52 @@ + +PDS Validate Tool Report + +Configuration: + Version 3.1.1 + Date 2023-03-18T18:12:55Z + +Parameters: + Targets [file:/home/runner/work/ldd-template/ldd-template/test/test1_FAIL.xml] + Rule Type pds4.label + User Specified Schemas [file:/home/runner/work/ldd-template/ldd-template/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.xsd, file:/tmp/PDS4_PDS_1J00.xsd] + User Specified Schematrons [file:/home/runner/work/ldd-template/ldd-template/build/development/2d9ed1f3f0bd5b102a64a1333d4b3bec1b9af142/1.19.0.0/PDS4_EXAMPLE_1J00_1000.sch, file:/tmp/PDS4_PDS_1J00.sch] + Severity Level WARNING + Recurse Directories true + File Filters Used [*.xml, *.XML] + Data Content Validation off + Product Level Validation on + Max Errors 100000 + Registered Contexts File /tmp/validate-3.1.1/resources/registered_context_products.json + + + +Product Level Validation Results + + FAIL: file:/home/runner/work/ldd-template/ldd-template/test/test1_FAIL.xml + ERROR [error.label.schema] line 46, 37: cvc-datatype-valid.1.2.1: 'foo' is not a valid value for 'integer'. + ERROR [error.label.schema] line 46, 37: cvc-type.3.1.3: The value 'foo' of element 'example:my_first_attribute' is not valid. + WARNING [warning.label.missing_schematron_spec] No schematron specification found in the label. + 1 product validation(s) completed + +Summary: + + 2 error(s) + 1 warning(s) + + Product Validation Summary: + 0 product(s) passed + 1 product(s) failed + 0 product(s) skipped + + Referential Integrity Check Summary: + 0 check(s) passed + 0 check(s) failed + 0 check(s) skipped + + Message Types: + 2 error.label.schema + 1 warning.label.missing_schematron_spec + +End of Report +Completed execution in 4323 ms + diff --git a/pds4_versions.txt b/pds4_versions.txt new file mode 100644 index 0000000..1627b77 --- /dev/null +++ b/pds4_versions.txt @@ -0,0 +1 @@ +1.19.0.0 diff --git a/src/PDS4_EXAMPLE_IngestLDD.xml b/src/PDS4_EXAMPLE_IngestLDD.xml new file mode 100644 index 0000000..d3d3bb0 --- /dev/null +++ b/src/PDS4_EXAMPLE_IngestLDD.xml @@ -0,0 +1,46 @@ + + + + + + Example LDD + 1.0.0.0 + Discipline + Doe, Jane + janedoe + example + 2030-04-10T18:00:00Z + + + my_first_attribute + 1.0 + my_first_attribute + false + Jane Doe + My first attribute + + + false + ASCII_Integer + Units_of_None + + + + + My_First_LDD + 1.0 + First + Jane Doe + My first class + true + + my_first_attribute + attribute_of + 1 + 1 + + + + diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..b61270d --- /dev/null +++ b/src/README.md @@ -0,0 +1,8 @@ +# LDD Source Directory + +This directory should contain one IngestLDD for the LDD being built. +The file name *must* end with the string "IngestLDD" in order for the +auto-generation script to recognize the file. + +**The auto-generation script does not currently support retaining or +building multiple versions of an LDD.** diff --git a/src/dependencies/README.md b/src/dependencies/README.md new file mode 100644 index 0000000..9d1c1d4 --- /dev/null +++ b/src/dependencies/README.md @@ -0,0 +1,5 @@ +# LDD Dependencies Directory + +This directory is used to great git submodules to link to other LDD repos that this LDD depends upon to build. + +For more information see [Getting to know your LDD Repo](https://pds-data-dictionaries.github.io/getting-started.html#getting-to-know-your-ldd-repo) \ No newline at end of file diff --git a/test/No.Data b/test/No.Data new file mode 100644 index 0000000..e69de29 diff --git a/test/README.md b/test/README.md new file mode 100644 index 0000000..3e6e19a --- /dev/null +++ b/test/README.md @@ -0,0 +1,3 @@ +# Regression Test Directory + +Test products should go here. See ldd-template repo for examples: https://github.com/pds-data-dictionaries/ldd-template/tree/master/test \ No newline at end of file diff --git a/test/test1_FAIL.xml b/test/test1_FAIL.xml new file mode 100644 index 0000000..96f1a7e --- /dev/null +++ b/test/test1_FAIL.xml @@ -0,0 +1,87 @@ + + + + + + + + + + urn:nasa:pds:bundle:collection:product + 1.0 + My First Product + [IM_VERSION] + Product_Observational + + + + 2020-01-01T00:00:00Z + 2022-01-01T00:00:00Z + + + + None + Individual Investigation + + urn:nasa:pds:context:investigation:individual.none + data_to_investigation + + + + + None + Telescope + + + + None + Comet + + + + + foo + + + + + + No.Data + 2019-04-30T19:32:42.000Z + + + test + 11264 + 3 + Last Index Fastest + + UnsignedByte + 1.0 + 0.0 + + + Band + 3 + 1 + + + Line + 1024 + 2 + + + Sample + 1024 + 3 + + + 0.0 + 0.0 + + + + diff --git a/test/test1_VALID.xml b/test/test1_VALID.xml new file mode 100644 index 0000000..99f2b7d --- /dev/null +++ b/test/test1_VALID.xml @@ -0,0 +1,87 @@ + + + + + + + + + + urn:nasa:pds:bundle:collection:product + 1.0 + My First Product + [IM_VERSION] + Product_Observational + + + + 2020-01-01T00:00:00Z + 2022-01-01T00:00:00Z + + + + None + Individual Investigation + + urn:nasa:pds:context:investigation:individual.none + data_to_investigation + + + + + None + Telescope + + + + None + Comet + + + + + 1 + + + + + + No.Data + 2019-04-30T19:32:42.000Z + + + test + 11264 + 3 + Last Index Fastest + + UnsignedByte + 1.0 + 0.0 + + + Band + 3 + 1 + + + Line + 1024 + 2 + + + Sample + 1024 + 3 + + + 0.0 + 0.0 + + + +