Merge branch 'ExaWorks:main' into main

Author: RamonAra209

CONTRIBUTING.md

@@ -8,13 +8,13 @@ details how to contribute in a standardized and efficient manner.
 
 ## Git Workflow Summary
 
-- Ensure that you've opened an Issue on Github and consensus around the
-  solution has be reached.
+- Ensure that you've opened an Issue on GitHub and consensus around the
+  solution has been reached.
   - Minor changes (e.g., grammatical fixes) do not require an Issue first.
-- Make a new branch for each separable set of changes — ["one task, one
-  branch"](https://mail.python.org/pipermail/ipython-dev/2010-October/005632.html).
-- [Each commit should make one change](https://dev.to/ruanbrandao/how-to-make-good-git-commits-256k).
-  to aide reviewing and (in the worst case) simplify reverting it in the future.
+- Make a new branch for each separable set of changes—["one task, one
+  branch."](https://mail.python.org/pipermail/ipython-dev/2010-October/005632.html).
+- [Each commit should make one change](https://dev.to/ruanbrandao/how-to-make-good-git-commits-256k)
+  to aid reviewing and (in the worst case) simplify reverting it in the future.
   - A patch commit message should consist of a single short (less than 50
     character) sentence summarizing the change, optionally followed by a blank line
     and then a more thorough description.
@@ -25,16 +25,16 @@ details how to contribute in a standardized and efficient manner.
   - If you do find yourself merging from upstream, consider [Rebasing on
     upstream](https://matplotlib.org/stable/devel/gitwash/development_workflow.html#rebase-on-trunk).
 - Submit a Pull Request from your feature branch against upstream.
-  - Use the Draft PR feature on Github or title your PR with `WIP` if your PR is
+  - Use the Draft PR feature on GitHub or title your PR with `WIP` if your PR is
     not ready for a complete review immediately upon submission.
-- Ask on the [Exaworks slack](https://exaworks.slack.com) if you get stuck.
+- Ask on the [Exaworks Slack](https://exaworks.slack.com) if you get stuck.
 
 
 ## Pull Request (PR) Merging Process
 
 - PR reviews should be timely. Both reviewer and PR issuer should make a good
   attempt at resolving the conversation as quickly as possible.
-- PR reviews exist to check obvious things aren't missed, not to achieve
+- PR reviews exist to check that obvious things aren't missed, not to achieve
   perfection.
 - A PR is eligible for merging if it has at least one approval from a
   project maintainer, no outstanding requested changes or discussions, and passes
@@ -55,16 +55,16 @@ under-the-hood. PEP8 compliance is also verified as part of the CI by `flake8`.
 
 ## Type Annotations
 
-As much python code in this repo as is feasible should include type annotations.
+As much Python code in this repo as is feasible should include type annotations.
 These type annotations can then be ingested and checked by `mypy`, which can be
 run with `make typecheck` and `make checks`.
 
 ## Docstrings
 
-As many public python interfaces in this repo as is feasible should
+As many public Python interfaces in this repo as is feasible should
 include docstring documentation. All docstrings should follow the
 [numpy format](https://numpydoc.readthedocs.io/en/latest/format.html). These
 docstrings are automatically parsed by Sphinx and turned into html-based
 documentation hosted on readthedocs. Document generation can be run locally
 with `make docs`. For more details about building the documentation, please
-see [`README-dev`][README-dev.md].
+see [`README-dev`](README-dev.md).

Makefile

@@ -51,7 +51,7 @@ docs:
 .PHONY: web-docs
 web-docs:
 	rm -rf docs/.generated
-	sphinx-build -W -b html -D html_theme='cloud' docs docs/.web-build/
+	sphinx-build -W -b html -D html_theme='cloud' -D templates_path='_templates' docs docs/.web-build/
 
 .PHONY: style
 style:

QuickStart.md

@@ -1,4 +1,4 @@
-# Quick start guide
+# Quick Start Guide
 
 This document will guide you through the install procedure and your first hello world example.
 
@@ -17,9 +17,9 @@ If you have conda installed you might want to start from a fresh environment. Th
 2. `conda activate psij`
 
 
-Install psij from the github repository:
+Install psij from the GitHub repository:
 
-1. Clone repository into your working directory:
+1. Clone the repository into your working directory:
 
     `git clone https://github.com/ExaWorks/psij-python.git`
 
@@ -32,15 +32,15 @@ Install psij from the github repository:
 
 
 
-## Hello world
+## Hello World
 
 **Requirements**
 - python3.7
-- job executioner, e.g. slurm in this example
+- Job executor, e.g. Slurm in this example
 
 **Steps**
 
-1. Create a file *my-workflow.py* and copy and paste the code below:
+1. Create a file *my-workflow.py* and copy and paste this code:
 
 ```python
 
@@ -82,7 +82,6 @@ for i in range(N):
     jobs[i].wait()
 
 ```
-2. In this example the number of jobs is 1. Set *N* to the number of jobs you want to run and save file.
+2. In this example the number of jobs is 1. Set *N* to the number of jobs you want to run and save the file.
 
 3. `python my-workflow.py`
-

README-dev.md

@@ -4,7 +4,7 @@
 
 There are two ways to build the documentation. One is the plain one, where
 the plain Sphinx output is desired, and the other is the themed version that
-is meant to integrate with the web site.
+is meant to integrate with the website.
 
 !!! Note
 
@@ -30,41 +30,49 @@ The output will be in `docs/.build`
 
 ### Building the Themed Documentation
 
-This builds the themed version of the docs as well as the web site. The steps
+This builds the themed version of the docs as well as the website. The steps
 are:
 
 1. Make sure you have the dependencies installed:
     ```sh
     pip install -r requirements-docs.txt
     ```
 
-2. Build the web site, which builds the themed version of the documentation
+2. Build the website, which builds the themed version of the documentation
 automatically:
     ```
     web/build.sh
     ```
 
 Make sure that `build.sh` is called from the main directory. The output will
-be in `web-build`. You are likely going to need to load it through a web
-server. A simple way to do so is:
+be in `web-build`.
+
+3. Render the web site and themed documentation, which can be done using Jekyll.
+To install Jekyll, follow the instructions in step 2 of 
+[web/README.md](web/README.md). You only need to do this once. Then run
 
     ```
-    cd web-build
-    python -m http.server <port>
+    web/serve.sh
     ```
 
-where `<port>` is a port number to start the HTTP server on.
+which will output something like this:
+```
+...
+    Server address: http://127.0.0.1:4000/psij-python/
+  Server running... press ctrl-c to stop.
+```
+
 
-When developing the web site, a convenient script is `web/watch.sh`, which can
-monitor the source directories and re-build when files are modified. This
-requires `inotify` which may or may not be available on your platform.
+Pointing your web browser to the URL printed by Jekyll will show the PSI/J
+web site. The themed documentation will be found under the "Documentation"
+tab.
 
 
-### Release process
+### Release Process
 
 Here are the steps for putting out a fresh release to Pypi.
 
-1. Create a new branch from main, and make release specific updates:
+1. Create a new branch from main and make release specific updates:
     * Update `src/psij/version.py` to the new version number
 
 2. Use the standard PR process and get changes from the above step merged to main.
@@ -73,6 +81,6 @@ Here are the steps for putting out a fresh release to Pypi.
    setup tokens on your machine.
 
 4. Run `make VERSION="version string" tag-and-release`. This will:
-    1. Create and push tags to github
-    2. Build the package
-    3. Push built package to Pypi.
+    * Create and push tags to GitHub.
+    * Build the package.
+    * Push built package to Pypi.

README-testing.md

@@ -10,16 +10,16 @@ are uploaded to a test aggregation service. The compatibility of various
 PSI/J branches with various resources can then be assessed and is
 available at https://testing.exaworks.org
 
-How to run tests
+How to Run Tests
 ================
 
 There are a number of ways to run tests. Invoking `pytest` directly,
-running the integration tests and through `cron` (or a similar tool).
+running the integration tests, and through `cron` (or a similar tool).
 
-Setting up an automated testing job
+Setting up an Automated Testing Job
 ===================================
 
-This is the preferred way of running the tests since it allows the PSI/J
+This is the preferred way of running tests since it allows the PSI/J
 team to keep a constant eye on the state of the library on various
 resources. To set up the Cron job (or an alternative method), you can either
 use the provided setup script:
@@ -37,7 +37,7 @@ virtual environment, please run the relevant commands before invoking
 `psij-ci-setup`.
 
 
-Testing with the CI runner
+Testing with the CI Runner
 ==========================
 
 The CI runner is a convenience script which can clone the PSI/J
@@ -106,4 +106,3 @@ or, using `make`, prefix all options with a double dash ("--"):
 Care must, however, be taken since it is impossible to preserve
 whitespace and certain special characters (such as the double quotes)
 when passing arguments through `make`.
-

README.md

@@ -14,8 +14,8 @@ documentation](https://exaworks.org/psij-python/#docs).
 
 ## Introduction
 
-1. [Quick start guide](QuickStart.md)
-2. [Workflow examples](scripts/WORKFLOW-EXAMPLES.md)
-3. [Setting up tests](README-testing.md)
-4. [How to contribute](CONTRIBUTING.md)
-5. [Building the documentation](README-dev.md)
+1. [Quick Start Guide](QuickStart.md)
+2. [Workflow Examples](scripts/WORKFLOW-EXAMPLES.md)
+3. [Setting up Tests](README-testing.md)
+4. [How to Contribute](CONTRIBUTING.md)
+5. [Building the Documentation](README-dev.md)

docs/README-selectors.md

@@ -26,6 +26,15 @@ selector. The string `"<&executor-type>"` must be a standalone token as
 far as the syntax highlighter is concerned. That is, it probably won't
 work if it's in a comment.
 
+An alternative string to `"<&executor-type>"` is `execparams.executor`.
+This so that one could have statements of the form
+
+    x = f(execparams.executor)
+
+works with the selector mechanism. This would allow rendering of
+verbatim functional test cases that parametrize the executor types and
+representing them with selectors in the documentation.
+
 To add alternative code blocks, use:
 
 ```Sphinx

docs/_static/extras.js

@@ -59,12 +59,28 @@ function detectAll(selectorType) {
     // Similarly, if "D" is selected in the second selector, we only want to change 
     // simple_value_2. However, if either "B" or "C" are selected in either selector,
     // we want to change both.
-    
+
+    console.log("type:" + selectorType);
     $("p." + selectorType + "-selector").addClass(selectorType + "-item");
+    var prevSpans = [];
     $("span").each(function() {
-        if ($(this).text() == '"<&' + selectorType + '>"') {
+        var text = $(this).text();
+        // look for both "<&<type>>" and execparams.<type> to align with test cases
+
+        if (text == '"<&' + selectorType + '>"') {
             $(this).addClass(selectorType + "-item").addClass("psij-selector-value");
         }
+        if (text == "executor" && prevSpans.length == 2
+            && prevSpans[0].text() == "execparams" && prevSpans[1].text() == '.') {
+            // remove <span>execparams</span> and <span>.</span>
+            prevSpans[0].remove();
+            prevSpans[1].remove();
+            $(this).addClass(selectorType + "-item").addClass("psij-selector-value");
+        }
+        prevSpans.push($(this));
+        if (prevSpans.length > 2) {
+            prevSpans.shift();
+        }
     });
 }
 

docs/_templates/layout.html

@@ -0,0 +1,34 @@
+{%- extends "cloud/layout.html" -%}
+
+{# We are not processing the output of these pages through Jekyll, so
+   we need to set the variables referenced in the includes. #}
+{% set site = {"baseurl": "/psij-python"} %}
+
+{% block scripts %}
+    {% include "../../web/_includes/head.html" %}
+    
+    {{ super() }}
+{% endblock %}
+
+{% block header %}
+    <v-app id="psij-app">
+        {% include "../../web/_includes/menu.html" %}
+        {{ super() }}
+{% endblock %}
+
+{% block footer %}
+        {{ super() }}
+        
+        {% include "../../web/_includes/footer.html" %}
+    </v-app>
+    
+    {# Same as above #}
+    {% set page = {"tab": 2} %}
+    {% include "../../web/_includes/vueinit.html" %}
+    
+
+{% endblock %}
+
+
+{% block sidebartoggle %}
+{% endblock %}

docs/_templates/searchbox.html

@@ -0,0 +1,18 @@
+{#
+    searchbox.html
+    ~~~~~~~~~~~~~~~~~~~~
+
+    Replaces basic/searchbox.html because vue.js does not like <script> without the type attribute
+#}
+{%- if pagename != "search" and builder != "singlehtml" %}
+<div id="searchbox" style="display: none" role="search">
+  <h3 id="searchlabel">{{ _('Quick search') }}</h3>
+    <div class="searchformwrapper">
+    <form class="search" action="{{ pathto('search') }}" method="get">
+      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
+      <input type="submit" value="{{ _('Go') }}" />
+    </form>
+    </div>
+</div>
+<script type="application/javascript">$('#searchbox').show(0);</script>
+{%- endif %}