Merge pull request #8 from usnistgov/docs

Zenodo Upload and Mkdocs

.github/workflows/conda.yml

@@ -17,7 +17,9 @@ jobs:
             python=3.10
             poetry
       - run: poetry install
-      - run: py.test --nbval-lax --cov-fail-under=100
+      - env:
+          ZENODO_SANDBOX_API_TOKEN: ${{ secrets.ZENODO_SANDBOX_API_TOKEN }}
+        run: py.test --nbval-lax --cov-fail-under=100
       - run: |
           mkdir -p tmp
           cd tmp

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+---
+name: Docs
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: .
+    steps:
+      - uses: actions/checkout@v3
+      - uses: cachix/install-nix-action@v20
+        with:
+          nix_path: nixpkgs=channel:nixos-unstable
+          name: pfhub
+          authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
+          extraPullNames: nix-community
+      - run: echo "UID=${UID}" >> $GITHUB_ENV
+      - uses: actions/cache/restore@v3
+        with:
+          path: /run/user/${{ env.UID }}/http_cache.sqlite
+          key: ${{ runner.os}}-http_cache.sqlite
+      - run: nix develop --command bash -c "mkdocs gh-deploy --clean --verbose --remote-branch nist-pages"
+      - uses: actions/cache/save@v3
+        if: always()
+        with:
+          path: /run/user/${{ env.UID }}/http_cache.sqlite
+          key: ${{ runner.os }}-http_cache.sqlite

.github/workflows/nix.yml

@@ -20,7 +20,9 @@ jobs:
         with:
           path: /run/user/${{ env.UID }}/http_cache.sqlite
           key: ${{ runner.os}}-http_cache.sqlite
-      - run: nix develop --command bash -c "py.test --nbval-lax --cov-fail-under=100"
+      - env:
+          ZENODO_SANDBOX_API_TOKEN: ${{ secrets.ZENODO_SANDBOX_API_TOKEN }}
+        run: nix develop --command bash -c "py.test --nbval-lax --cov-fail-under=100"
       - run: nix develop --command bash -c "black --check pfhub"
       - run: nix develop --command bash -c "pylint pfhub"
       - run: nix develop --command bash -c "flake8 pfhub"

.gitignore

@@ -1,3 +1,5 @@
 .~*
 .coverage
 dist
+site
+tmp

DEVELOPMENT.md

@@ -152,3 +152,55 @@ To publish, use
 [flakes]: https://nixos.wiki/wiki/Flakes
 [conventional]: https://www.conventionalcommits.org
 [pypi-test]: https://stackoverflow.com/questions/68882603/using-python-poetry-to-publish-to-test-pypi-org
+
+### Deploying the docs
+
+Use
+
+    $ mkdocs gh-deploy --remote-branch nist-pages --remote-name upstream
+
+when in the nix development environment. This will build the docs and
+push to the `nist-pages` branch in the upstream repository.
+
+
+
+### Setting up Zenodo
+
+It's best to start testing uploads using Zenodo Sandbox before using
+the main Zenodo repository. See [the zenodo-client
+documentation](https://pypi.org/project/zenodo-client/) for more
+details, but the following steps should work:
+
+ - Create an account with Zenodo sandbox at
+   [https://sandbox.zenodo.org/signup/](https://sandbox.zenodo.org/signup/).
+
+ - Generate a Zenodo token from
+   [https://sandbox.zenodo.org/account/settings/applications/](https://sandbox.zenodo.org/account/settings/applications/)
+   under "Applications" > "Personal Access Tokens". Select
+   "deposits:actions", "deposits:write" and "user:email" when
+   generating the token.
+
+ - Copy the token and set the `ZENODO_SANDBOX_API_TOKEN` environment
+   variable using the token or add the token to `~/.config/zenodo.ini`
+   so that it looks like
+
+```
+[zenodo]
+sandbox_api_token = XXX
+
+```
+
+ - Test using the PFHub CLI to upload data to Zenodo Sandbox. Use
+   `pfhub upload pfhub.yaml --sandbox` to do this. Sample data is
+   available here
+   [here](https://github.com/usnistgov/pfhub-cli/tree/main/pfhub/test_data).
+
+
+**NOTE**: logging into Zenodo's sandbox can be difficult with ORCID
+and is probably easier with a GitHub ID.
+
+To use the main Zenodo repository (not sandbox), follow the same
+instructions as above, but use the main Zenodo site. Set the
+`ZENODO_API_TOKEN` or add the `api_token = XXX` to
+`~/.config/zenodo.ini`.
+

README.md

@@ -1,5 +1,7 @@
 # PFHub CLI
 
+## Overview
+
 A Python module for both rendering and submitting [PFHub] phase-field
 benchmark results using Jupyter, Pandas and Plotly.
 
@@ -27,7 +29,7 @@ for just the command line tool or
     $ nix develop github:usnistgov/pfhub-cli
 
 to generate an environment with Python and Jupyter available.  See
-[the Nix section of the development guide](./DEVELOPMENT.md#flakes) to
+[the Nix section of the development guide](./DEVELOPMENT.md#nix-shell-prompt) to
 get more help starting out with Nix.
 
 ## Usage
@@ -37,7 +39,10 @@ get more help starting out with Nix.
 To test that the PFHub CLI is installed correctly use
 
     $ pfhub test
-        
+
+A single test will fail if `ZENODO_SANDBOX_API_TOKEN` is not set, see
+the [development guide](./DEVELOPMENT.md#setting-up-zenodo).
+
 ### Submit a benchmark result
 
 Under construction.

docs/DEVELOPMENT.md

@@ -0,0 +1,2 @@
+--8<-- "DEVELOPMENT.md"
+

docs/LICENSE.md

@@ -0,0 +1 @@
+--8<-- "LICENSE.md"

docs/api.md

@@ -0,0 +1,17 @@
+# API
+
+
+::: pfhub.main
+    options:
+      members:
+        - efficiency_plot
+        - levelset_plot
+      show_root_heading: true
+      show_source: true
+
+::: pfhub.scripts.cli
+    options:
+      members:
+        - download_zenodo
+      show_root_heading: true
+      show_source: true

docs/css/extra.css

@@ -0,0 +1,4 @@
+.highlight.language-python {
+    color: #3E4349;
+    font-size: 16px;
+}

docs/index.md

@@ -0,0 +1,2 @@
+--8<-- "README.md"
+

flake.nix

@@ -19,6 +19,8 @@
         url-normalize = [ "poetry-core" ];
         cfgraph = [ "setuptools" ];
         pytest-logging = [ "setuptools" ];
+        mkdocs-windmill = [ "setuptools" ];
+        paginate = [ "setuptools" ];
       };
 
       p2n-overrides = pkgs.poetry2nix.defaultPoetryOverrides.extend (self: super:

mkdocs.yml

@@ -0,0 +1,67 @@
+site_name: PFHub CLI
+site_url: https://example.com/
+repo_url: https://github.com/usnistgov/pfhub-cli
+
+theme:
+  name: material
+  palette:
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+nav:
+  - Home: index.md
+  # - Tutorial: tutorial.md
+  - "How-to Guide":
+    - "Test Notebook include": notebooks/test
+    # - "Upload Data to Zenodo": upload-zenodo.md
+    # - "Submit a Benchmark Result": test
+    # - "Generate Data": generate.md
+    # - "Generate a pfhub.yaml": pfhub-yaml.md
+  # - Background: background.md        
+  - API: api.md
+  - Development: DEVELOPMENT.md
+
+markdown_extensions:
+  - pymdownx.snippets:
+      check_paths: true
+  - toc:
+      permalink: "¶"
+
+plugins:
+  - mkdocs-jupyter:
+      execute: true
+      allow_errors: false
+      include_requirejs: true
+      ignore: [".ipynb_checkpoints/*.ipynb"]
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            docstring_section_style: list
+            # heading_level: 1
+            inherited_members: true
+            merge_init_into_class: true
+            separate_signature: true
+            show_root_heading: true
+            show_root_full_path: false
+            show_signature_annotations: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+            summary: true
+            parameter_headings: true
+
+extra_css:
+  - extra.css

pfhub/__init__.py

@@ -25,17 +25,7 @@ def test(*args):  # pragma: no cover
     import pytest  # pylint: disable=import-outside-toplevel
 
     path = os.path.join(os.path.split(__file__)[0])
-    pytest.main(
-        args=[
-            path,
-            "--doctest-modules",
-            "-r s",
-            "--cov=pfhub/",
-            "--no-cov-on-fail",
-            "--cov-fail-under=100",
-        ]
-        + list(args)
-    )
+    pytest.main(args=[path, "--doctest-modules", "-r s", "--no-cov"] + list(args))
 
 
 __version__ = _version.get_versions()["version"]

pfhub/convert.py

@@ -315,7 +315,7 @@ def get_file_strings(meta_yaml):
       meta_yaml: wizdot version of meta.yaml
 
     Returns:
-      a dictionary of files and contents for wring to disk including
+      a dictionary of files and contents for writing to disk including
       the pfhub.yaml and necessary data files
 
     >>> yaml_file = str(getfixture('yaml_data_file'))
@@ -406,7 +406,7 @@ def render_pfhub_schema(data, time_data, memory_data, timeseries):
         {
             "problem": data.benchmark.id,
             "benchmark_version": data.benchmark.version,
-            "summary": data.metadata.summary,
+            "summary": data.metadata.summary.encode("unicode_escape"),
             "contributors": [
                 {
                     "id": "github:" + data.metadata.author.github_id,

pfhub/func.py

@@ -376,7 +376,7 @@ def compact(items):
 
 
 def read_vega_data(keys, data):
-    """Read vega data given keys to exract
+    """Read vega data given keys to extract
 
     Read a vega data block given the keys (or columns) to extract
 

pfhub/main.py

@@ -387,13 +387,16 @@ def line_plot(
 def levelset_plot(
     data, layout=None, columns=("x", "y", "z"), mask_func=lambda x: slice(len(x))
 ):
-    """Generate a Plotly level set plot
+    r"""Generate a Plotly level set plot
 
     Args:
       data: extracted data as a data frame
       layout: dictionary with "x", "y" and "title" keys to customize the plot
       mask_func: function to apply to remove values (helps to reduce memory usage)
 
+    Example:
+
+    ```
     >>> x, y = np.mgrid[-1:1:10j, -1:1:10j]
     >>> x = x.flatten()
     >>> y = y.flatten()
@@ -416,6 +419,7 @@ def levelset_plot(
                    'yaxis': {'range': [-1, 1], 'scaleanchor': 'x', 'scaleratio': 1}}
     })
 
+    ```
     """
     if layout is None:
         layout = {}

pfhub/schema/pfhub_schema.yaml

@@ -300,7 +300,7 @@ slots:
   time_in_s:
     description: >-
       Amount of time required to execute the simulation.
-    range: integer
+    range: float
     required: true
     slot_uri: https://schema.org/Number
     unit:

pfhub/scripts/cli.py

@@ -22,6 +22,7 @@
 from ..convert import download_meta as download_meta_
 from ..func import compact
 from ..new_to_old import to_old
+from ..upload import upload_to_zenodo
 
 
 EPILOG = "See the documentation at \
@@ -234,15 +235,16 @@ def test():  # pragma: no cover
 
 
 @cli.command(epilog=EPILOG)
-@click.option(
-    "--path",
-    "-p",
-    help="Upload a set of files to Zenodo",
-    type=click.Path(exists=True, readable=True, file_okay=False),
-    default="./",
+@click.argument(
+    "file_path",
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    default="./pfhub.yaml",
 )
-def upload(path):  # pylint: disable=unused-argument
+@click.option("--sandbox/--no-sandbox", default=True)
+def upload(file_path, sandbox):  # pylint: disable=unused-argument
     """Upload PFHub data to Zenodo"""
+    url = upload_to_zenodo(file_path, sandbox)
+    click.secho(message=f"Uploaded to {url}", fg="green")
 
 
 @cli.command(epilog=EPILOG)