Merge pull request #338 from ExaWorks/330-automatic-test-of-some-documentation-code

330 automatic test of some documentation code

Author: hategan

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/getting_started.rst

@@ -79,7 +79,7 @@ Local // Slurm // LSF // PBS // Cobalt
 
     from psij import Job, JobExecutor, JobSpec
 
-    ex = JobExecutor.get_instance("<&executor-type>")
+    ex = JobExecutor.get_instance(execparams.executor)
     job = Job(JobSpec(executable="/bin/date"))
     ex.submit(job)
 

docs/user_guide.rst

@@ -100,13 +100,10 @@ On a Slurm cluster, this code might look like:
 
 Slurm // Local // LSF // PBS // Cobalt
 
-.. code-block:: python
-
-    from psij import Job, JobExecutor, JobSpec
-
-    ex = JobExecutor.get_instance("<&executor-type>")
-    job = Job(JobSpec(executable='/bin/date'))
-    ex.submit(job)
+.. literalinclude:: ../tests/getting_started/test_single_job.py
+    :language: python
+    :dedent: 4
+    :lines: 6-8
 
 And by way of comparison, other backends can be selected with the tabs above.
 Note that the only difference is the argument to the ``get_instance`` method.
@@ -129,14 +126,10 @@ simple as adding a loop:
 
 Slurm // Local // LSF // PBS // Cobalt
 
-.. code-block:: python
-
-    from psij import Job, JobExecutor, JobSpec
-
-    ex = JobExecutor.get_instance("<&executor-type>")
-    for _ in range(10):
-        job = Job(JobSpec(executable="/bin/date"))
-        ex.submit(job)
+.. literalinclude:: ../tests/getting_started/test_multiple_jobs.py
+    :language: python
+    :dedent: 4
+    :lines: 6-9
 
 Every :class:`JobExecutor <psij.job_executor.JobExecutor>` can handle arbitrary
 numbers of jobs (tested with up to 64k jobs).
@@ -171,13 +164,10 @@ formatting:
 
 Slurm // Local // LSF // PBS // Cobalt
 
-.. code-block:: python
-
-    from psij import Job, JobExecutor, JobSpec
-
-    ex = JobExecutor.get_instance('<&executor-type>')
-    job = Job(JobSpec(executable='/bin/date', arguments=['-utc', '--debug']))
-    ex.submit(job)
+.. literalinclude:: ../tests/getting_started/test_job_arguements.py
+    :language: python
+    :dedent: 4
+    :lines: 6-8
 
 Note: `JobSpec` attributes can also be added incrementally:
 
@@ -305,23 +295,10 @@ attributes=my_job_attributes)``:
 
 Slurm // Local // LSF // PBS // Cobalt
 
-.. code-block:: python
-
-    from psij import Job, JobExecutor, JobSpec, JobAttributes, ResourceSpecV1
-
-    executor = JobExecutor.get_instance("<&executor-type>")
-
-    job = Job(
-        JobSpec(
-            executable="/bin/date",
-            resources=ResourceSpecV1(node_count=1),
-            attributes=JobAttributes(
-                queue_name="<QUEUE_NAME>", project_name="<ALLOCATION>"
-            ),
-        )
-    )
-
-    executor.submit(job)
+.. literalinclude:: ../tests/getting_started/test_scheduling_information.py
+    :language: python
+    :dedent: 4
+    :lines: 7-20
 
 The `<QUEUE_NAME>` and `<ALLOCATION>` fields will depend on the system you are
 running on.
@@ -392,29 +369,14 @@ To wait on multiple jobs at once:
 
 Slurm // Local // LSF // PBS // Cobalt
 
-.. code-block:: python
-
-    import time
-    from psij import Job, JobExecutor, JobSpec
-
-    count = 10
-
-    def callback(job, status):
-        global count
-
-        if status.final:
-            print(f"Job {job} completed with status {status}")
-            count -= 1
-
-    ex = JobExecutor.get_instance("<&executor-type>")
-    ex.set_job_status_callback(callback)
-
-    for _ in range(count):
-        job = Job(JobSpec(executable="/bin/date"))
-        ex.submit(job)
+.. literalinclude:: ../tests/getting_started/test_status_callbacks.py
+    :language: python
+    :lines: 5
 
-    while count > 0:
-        time.sleep(0.01)
+.. literalinclude:: ../tests/getting_started/test_status_callbacks.py
+    :language: python
+    :dedent: 4
+    :lines: 9-24
 
 Status callbacks can also be set on individual jobs with
 :meth:`set_job_status_callback <psij.job.Job.set_job_status_callback>`.

tests/getting_started/test_job_arguements.py

@@ -0,0 +1,8 @@
+from psij import Job, JobSpec, JobExecutor
+from executor_test_params import ExecutorTestParams
+
+
+def test_getting_started_job_arguements(execparams: ExecutorTestParams) -> None:
+    ex = JobExecutor.get_instance(execparams.executor)
+    job = Job(JobSpec(executable='/bin/date', arguments=['-utc', '--debug']))
+    ex.submit(job)

tests/getting_started/test_multiple_jobs.py

@@ -0,0 +1,9 @@
+from psij import Job, JobSpec, JobExecutor
+from executor_test_params import ExecutorTestParams
+
+
+def test_getting_started_multiple_jobs(execparams: ExecutorTestParams) -> None:
+    ex = JobExecutor.get_instance(execparams.executor)
+    for _ in range(10):
+        job = Job(JobSpec(executable="/bin/date"))
+        ex.submit(job)

tests/getting_started/test_scheduling_information.py

@@ -0,0 +1,20 @@
+from psij import Job, JobSpec, JobExecutor, ResourceSpecV1
+# from psij import JobAttributes
+from executor_test_params import ExecutorTestParams
+
+
+def test_getting_started_scheduling_info(execparams: ExecutorTestParams) -> None:
+    executor = JobExecutor.get_instance(execparams.executor)
+
+    job = Job(
+        JobSpec(
+            executable="/bin/date",
+            resources=ResourceSpecV1(node_count=1),
+            # attributes=JobAttributes(
+            #     queue_name="<QUEUE_NAME>",
+            #     project_name="<ALLOCATION>"
+            # ),
+        )
+    )
+
+    executor.submit(job)

tests/getting_started/test_single_job.py

@@ -0,0 +1,8 @@
+from psij import Job, JobSpec, JobExecutor
+from executor_test_params import ExecutorTestParams
+
+
+def test_getting_started_single_job(execparams: ExecutorTestParams) -> None:
+    ex = JobExecutor.get_instance(execparams.executor)
+    job = Job(JobSpec(executable='/bin/date', arguments=['-utc', '--debug']))
+    ex.submit(job)

tests/getting_started/test_status_callbacks.py

@@ -0,0 +1,24 @@
+import time
+from psij import Job, JobSpec, JobStatus, JobExecutor
+from executor_test_params import ExecutorTestParams
+
+count = 10
+
+
+def test_getting_started_scheduling_info(execparams: ExecutorTestParams) -> None:
+    def callback(job: Job, status: JobStatus) -> None:
+        global count
+
+        if status.final:
+            print(f"Job {job} completed with status {status}")
+            count -= 1
+
+    ex = JobExecutor.get_instance(execparams.executor)
+    ex.set_job_status_callback(callback)
+
+    for _ in range(count):
+        job = Job(JobSpec(executable="/bin/date"))
+        ex.submit(job)
+
+    while count > 0:
+        time.sleep(0.01)