Merge pull request #5 from smaht-dac/kmp_submitr_logo

Documentation updates (C4-1084)

.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 # Distribution / packaging
 .Python
 build/
+docs/html/
 develop-eggs/
 dist/
 downloads/

CHANGELOG.rst

@@ -6,6 +6,14 @@ submitr
 Change Log
 ----------
 
+0.3.0
+=====
+
+* Add a pretty logo
+* Warn about not yet being still experimental.
+* Better badges.
+
+
 0.2.1
 =====
 

Makefile

@@ -26,6 +26,10 @@ update:  # updates dependencies
 tag-and-push:  # tags the branch and pushes it
 	@scripts/tag-and-push
 
+preview-locally:
+	sphinx-build -b html docs/source docs/html
+	open docs/html/index.html
+
 publish:
 	# New Python based publish script in dcicutils (2023-04-25).
 	poetry run publish-to-pypi
@@ -42,6 +46,7 @@ info:
 	   $(info - Use 'make configure' to install poetry, though 'make build' will do it automatically.)
 	   $(info - Use 'make lint' to check style with flake8.)
 	   $(info - Use 'make build' to install dependencies using poetry.)
+	   $(info - Use 'make preview-locally' to build and a local doc tree and open it for preview.)
 	   $(info - Use 'make publish' to publish this library, but only if auto-publishing has failed.)
 	   $(info - Use 'make retest' to run failing tests from the previous test run.)
 	   $(info - Use 'make test' to run tests with the normal options we use for CI/CD like GA.)

README.rst

@@ -1,3 +1,19 @@
+
+.. image:: docs/source/_static/images/submitr-banner.png
+    :target: https://pypi.org/project/submitr/
+    :alt: SMaHT remote Metadata Submission Tool: submitr
+    :align: center
+
+|
+
+**THIS IS A PRE-RELEASE VERSION.**
+
+This was recently forked from SubmitCGAP and is not yet ready for normal use.
+
+Watch for version 1.0.
+
+------------
+
 =======
 submitr
 =======
@@ -10,19 +26,14 @@ A file submission tool for SMAHT
    :target: https://github.com/smaht-dac/submitr/actions
    :alt: Build Status
 
-.. image:: https://coveralls.io/repos/github/dbmi-bgm/submitr/badge.svg
-   :target: https://coveralls.io/github/smaht-dac/submitr
-   :alt: Coverage
+.. image:: https://coveralls.io/repos/github/smaht-dac/submitr/badge.svg
+    :target: https://coveralls.io/github/smaht-dac/submitr
+    :alt: Coverage Percentage
 
 .. image:: https://readthedocs.org/projects/submitr/badge/?version=latest
    :target: https://submitr.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status
 
-.. warning::
-
-   THIS IS A PRE-RELEASE VERSION.
-
-   It was recently forked. It is not yet ready for normal use. Watch for version 1.0.
 
 Description
 ===========

docs/source/index.rst

@@ -1,18 +1,34 @@
+.. image:: /_static/images/submitr-banner.png
+    :target: https://pypi.org/project/submitr/
+    :alt: SMaHT remote Metadata Submission Tool: submitr
+    :align: center
+
+|
+
+.. warning::
+
+   **THIS IS A PRE-RELEASE VERSION.**
+
+   This was recently forked from SubmitCGAP and is not yet ready for normal use.
+
+   Watch for version 1.0.
+
+
 ========
 Overview
 ========
 
-
-File submission for submitr
----------------------------
+----------------------------------------
+submitr: remote file submitter for SMaHT
+----------------------------------------
 
 .. image:: https://github.com/smaht-dac/submitr/actions/workflows/main.yml/badge.svg
     :target: https://github.com/smaht-dac/submitr/actions
     :alt: Build Status
 
-.. image:: https://coveralls.io/repos/github/dbmi-bgm/submitr/badge.svg
+.. image:: https://coveralls.io/repos/github/smaht-dac/submitr/badge.svg
     :target: https://coveralls.io/github/smaht-dac/submitr
-    :alt: Coverage
+    :alt: Coverage Percentage
 
 .. image:: https://readthedocs.org/projects/submitr/badge/?version=latest
     :target: https://submitr.readthedocs.io/en/latest/?badge=latest

docs/source/submitr.rst

@@ -1,5 +1,5 @@
 submitr package
-====================
+===============
 
 Subpackages
 -----------
@@ -13,40 +13,32 @@ Subpackages
 Submodules
 ----------
 
-submitr.auth module
-------------------------
-
-.. automodule:: submitr.auth
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 submitr.base module
-------------------------
+-------------------
 
 .. automodule:: submitr.base
    :members:
    :undoc-members:
    :show-inheritance:
 
 submitr.exceptions module
-------------------------------
+-------------------------
 
 .. automodule:: submitr.exceptions
    :members:
    :undoc-members:
    :show-inheritance:
 
 submitr.submission module
-------------------------------
+-------------------------
 
 .. automodule:: submitr.submission
    :members:
    :undoc-members:
    :show-inheritance:
 
 submitr.utils module
--------------------------
+--------------------
 
 .. automodule:: submitr.utils
    :members:

docs/source/submitr.tests.rst

@@ -4,14 +4,6 @@ submitr.tests package
 Submodules
 ----------
 
-submitr.tests.test\_auth module
-------------------------------------
-
-.. automodule:: submitr.tests.test_auth
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 submitr.tests.test\_base module
 ------------------------------------
 

pyproject.toml

@@ -1,7 +1,8 @@
 [tool.poetry]
 name = "submitr"
-version = "0.2.1"
+version = "0.3.0"
 description = "Support for uploading file submissions to SMAHT."
+# TODO: Update this email address when a more specific one is available for SMaHT.
 authors = ["4DN-DCIC Team <[email protected]>"]
 license = "MIT"
 readme = "README.rst"
@@ -49,6 +50,16 @@ python = ">=3.7.0,<3.10"
 awscli = "^1.27.79"
 # boto3 = "^1.26.79"
 dcicutils = "^7.7.1"
+# TODO: Consider an upgrade to PyYAML 6.
+# David wanted PyYAML 5 pinned at 5.3.1 for M1, but noted we should investigate upgrading to PyYAML 6.
+# Specifically, on https://github.com/smaht-dac/submitr/pull/5, he wrote:
+#   << Looks like at least for M1 will have to pin pyyaml to 5.3.1 (or 6.0 but dcicutils has restriction on that). >>
+# Kent asked whether 5.3.1 or ^5.3.1, and also if PyYAML 6 has incompatibilities. David wrote:
+#   << M1 only 5.3.1 specifically or 6.0 or 6.0.1 installs without error.
+#      At least according the pyyaml change log (https://github.com/yaml/pyyaml/blob/master/CHANGES)
+#      I don't see anything too scary WRT updating generally (e.g. dcicutils)
+#      to 6.0.1 (except maybe "always require Loader arg to yaml.load()"). >>
+PyYAML = "5.3.1"  # pinned for M1. See notes above.
 requests = "^2.28.2"
 
 [tool.poetry.dev-dependencies]

submitr/submission.py

@@ -782,7 +782,7 @@ def show_upload_info(uuid, server=None, env=None, keydict=None, app: str = None,
     :param keydict: keydict-style auth, a dictionary of 'key', 'secret', and 'server'
     :param app: the name of the app to use
         e.g., affects whether to expect --lab, --award, --institution, --project, --consortium or --submission_center
-              and whether to use .fourfront-keys.json, .cgap-keys.json, or .smaht-keys.json
+        and whether to use .fourfront-keys.json, .cgap-keys.json, or .smaht-keys.json
     :param show_primary_result: bool controls whether the primary result is shown
     :param show_validation_output: bool controls whether to show output resulting from validation checks
     :param show_processing_status: bool controls whether to show the current processing status