From 1bfca83127fad8a3835c02e609e58401111c6fbe Mon Sep 17 00:00:00 2001 From: HansBug Date: Tue, 1 Feb 2022 22:50:23 +0800 Subject: [PATCH] doc(usage): add documentation for advanced usage --- docs/source/index.rst | 1 + .../source/tutorials/advanced_usage/index.rst | 134 ++++++++++++++++++ .../advanced_usage/spj_additional.py | 19 +++ .../spj_additional_demo_1.demo.sh | 1 + .../spj_additional_demo_2.demo.sh | 1 + .../advanced_usage/spj_continuity.py | 14 ++ .../spj_continuity_demo_1.demo.sh | 1 + .../spj_continuity_demo_2.demo.sh | 1 + .../spj_continuity_demo_x.demo.sh | 1 + .../tutorials/advanced_usage/spj_runnable.py | 28 ++++ .../advanced_usage/spj_runnable_help.demo.sh | 1 + .../advanced_usage/spj_runnable_installer.sh | 1 + .../spj_runnable_version.demo.sh | 1 + requirements-doc.txt | 1 + 14 files changed, 205 insertions(+) create mode 100644 docs/source/tutorials/advanced_usage/index.rst create mode 100644 docs/source/tutorials/advanced_usage/spj_additional.py create mode 100644 docs/source/tutorials/advanced_usage/spj_additional_demo_1.demo.sh create mode 100644 docs/source/tutorials/advanced_usage/spj_additional_demo_2.demo.sh create mode 100644 docs/source/tutorials/advanced_usage/spj_continuity.py create mode 100644 docs/source/tutorials/advanced_usage/spj_continuity_demo_1.demo.sh create mode 100644 docs/source/tutorials/advanced_usage/spj_continuity_demo_2.demo.sh create mode 100644 docs/source/tutorials/advanced_usage/spj_continuity_demo_x.demo.sh create mode 100644 docs/source/tutorials/advanced_usage/spj_runnable.py create mode 100644 docs/source/tutorials/advanced_usage/spj_runnable_help.demo.sh create mode 100644 docs/source/tutorials/advanced_usage/spj_runnable_installer.sh create mode 100644 docs/source/tutorials/advanced_usage/spj_runnable_version.demo.sh diff --git a/docs/source/index.rst b/docs/source/index.rst index 9817dc8..f65f2eb 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,6 +14,7 @@ imported and built. tutorials/installation/index tutorials/quick_start/index + tutorials/advanced_usage/index .. toctree:: :maxdepth: 2 diff --git a/docs/source/tutorials/advanced_usage/index.rst b/docs/source/tutorials/advanced_usage/index.rst new file mode 100644 index 0000000..6761e31 --- /dev/null +++ b/docs/source/tutorials/advanced_usage/index.rst @@ -0,0 +1,134 @@ +Advanced Usage +======================== + +Continuity Special Judge +---------------------------- + +Sometimes, we need to use special judge not only for predicating \ +the correctness of output result, but the quality of result as well. \ +So we can return a tuple of values which represent correctness and \ +score to do this. Like the following code which is named ``spj_continuity.spj``. + +.. literalinclude:: spj_continuity.py + :language: python + :linenos: + +Here is an example of correct result, but it is obviously not the \ +best one. + +.. literalinclude:: spj_continuity_demo_1.demo.sh + :language: shell + :linenos: + +.. literalinclude:: spj_continuity_demo_1.demo.sh.txt + :language: text + :linenos: + +Another example of correct result, which is better than the \ +abovementioned one. + +.. literalinclude:: spj_continuity_demo_2.demo.sh + :language: shell + :linenos: + +.. literalinclude:: spj_continuity_demo_2.demo.sh.txt + :language: text + :linenos: + +And then a wrong example as shown in following part. + +.. literalinclude:: spj_continuity_demo_x.demo.sh + :language: shell + :linenos: + +.. literalinclude:: spj_continuity_demo_x.demo.sh.txt + :language: text + :linenos: + + +Addtional Arguments +---------------------------- + +In some complex cases, additional arguments need to be passed into \ +the special judge function, such as the mode of special judge, or \ +something like the extra required data file's path. \ +Like the following code which is named ``spj_additional.py`` + +.. literalinclude:: spj_additional.py + :language: python + :linenos: + +Here is an common example + +.. literalinclude:: spj_additional_demo_1.demo.sh + :language: shell + :linenos: + +.. literalinclude:: spj_additional_demo_1.demo.sh.txt + :language: text + :linenos: + +And, if you want the input to be separated by ``,``, just use the \ +``-V`` option, like the command line below + +.. literalinclude:: spj_additional_demo_2.demo.sh + :language: shell + :linenos: + +.. literalinclude:: spj_additional_demo_2.demo.sh.txt + :language: text + :linenos: + + +.. note:: + + File import features (like ``-I`` and ``-O`` options`) \ + are not supported in addtional arguments. + + If you need to load the content of a data file, just pass \ + the path of the data file by additional arguments, and then \ + manually load the file in your special judge function. + + +Create My Runnable Special Judge CLI +------------------------------------------- + +You can create your own special judge CLI with the \ +``pyspj_entry`` function. Like the following code named \ +``spj_runnable.py``. + +.. literalinclude:: spj_runnable.py + :language: python + :linenos: + +You can see its version information. + +.. literalinclude:: spj_runnable_version.demo.sh + :language: shell + :linenos: + +.. literalinclude:: spj_runnable_version.demo.sh.txt + :language: text + :linenos: + +And see its help information, which is almost the same as the \ +native ``pyspj`` CLI. + +.. literalinclude:: spj_runnable_help.demo.sh + :language: shell + :linenos: + +.. literalinclude:: spj_runnable_help.demo.sh.txt + :language: text + :linenos: + +The cli script ``spj_runnable.py`` created by yourself can be used \ +like the ``pyspj`` CLI. + +Besides, this runnable special judge script can be built to a \ +standalone special judge executable file if needed. + +.. literalinclude:: spj_runnable_installer.sh + :language: shell + :linenos: + diff --git a/docs/source/tutorials/advanced_usage/spj_additional.py b/docs/source/tutorials/advanced_usage/spj_additional.py new file mode 100644 index 0000000..3af83a0 --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_additional.py @@ -0,0 +1,19 @@ +def additional_spj_func(stdin, stdout, sep=' '): + inputs = [int(item.strip()) for item in stdin.read().strip().split(sep) if item] + _correct_sum = sum(inputs) + + outputs = stdout.read().strip().split(' ', maxsplit=2) + if len(outputs) >= 1: + _result = int(outputs[0]) + else: + return False, 'No output found.' + + if _result == _correct_sum: + return True, 'Correct result.', 'Oh yeah, well done ^_^.' + else: + return False, 'Result {correct} expected but {actual} found.'.format( + correct=repr(_correct_sum), actual=repr(_result) + ) + + +__spj__ = additional_spj_func diff --git a/docs/source/tutorials/advanced_usage/spj_additional_demo_1.demo.sh b/docs/source/tutorials/advanced_usage/spj_additional_demo_1.demo.sh new file mode 100644 index 0000000..dd82c6f --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_additional_demo_1.demo.sh @@ -0,0 +1 @@ +pyspj -i '1 2 3 4 5' -o 15 -s spj_additional -V 'sep= ' \ No newline at end of file diff --git a/docs/source/tutorials/advanced_usage/spj_additional_demo_2.demo.sh b/docs/source/tutorials/advanced_usage/spj_additional_demo_2.demo.sh new file mode 100644 index 0000000..5c328b2 --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_additional_demo_2.demo.sh @@ -0,0 +1 @@ +pyspj -i '1,2,3,4,5' -o 15 -s spj_additional -V 'sep=,' diff --git a/docs/source/tutorials/advanced_usage/spj_continuity.py b/docs/source/tutorials/advanced_usage/spj_continuity.py new file mode 100644 index 0000000..69f6f02 --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_continuity.py @@ -0,0 +1,14 @@ +def continuity_spj_func(stdin, stdout): + _expected_sum = int(stdin.read().strip()) + + output_items = [int(item.strip()) for item in stdout.read().strip().split(' ') if item] + _actual_sum = sum(output_items) + _actual_cnt = len(output_items) + + if _expected_sum == _actual_sum: + return (True, 1 - (_actual_cnt - 1) / _expected_sum), 'Correct result.', 'Oh yeah, well done ^_^.' + else: + return (False, 0), f'Result {_expected_sum} expected but {_actual_sum} found.' + + +__spj__ = continuity_spj_func diff --git a/docs/source/tutorials/advanced_usage/spj_continuity_demo_1.demo.sh b/docs/source/tutorials/advanced_usage/spj_continuity_demo_1.demo.sh new file mode 100644 index 0000000..87412e3 --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_continuity_demo_1.demo.sh @@ -0,0 +1 @@ +pyspj -i '15' -o '1 2 3 4 5' -s spj_continuity -p \ No newline at end of file diff --git a/docs/source/tutorials/advanced_usage/spj_continuity_demo_2.demo.sh b/docs/source/tutorials/advanced_usage/spj_continuity_demo_2.demo.sh new file mode 100644 index 0000000..620e29d --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_continuity_demo_2.demo.sh @@ -0,0 +1 @@ +pyspj -i '15' -o '7 8' -s spj_continuity -p \ No newline at end of file diff --git a/docs/source/tutorials/advanced_usage/spj_continuity_demo_x.demo.sh b/docs/source/tutorials/advanced_usage/spj_continuity_demo_x.demo.sh new file mode 100644 index 0000000..5106f48 --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_continuity_demo_x.demo.sh @@ -0,0 +1 @@ +pyspj -i '15' -o '7 8 8' -s spj_continuity -p \ No newline at end of file diff --git a/docs/source/tutorials/advanced_usage/spj_runnable.py b/docs/source/tutorials/advanced_usage/spj_runnable.py new file mode 100644 index 0000000..81a821c --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_runnable.py @@ -0,0 +1,28 @@ +from pyspj.entry import pyspj_entry + + +def spj_func(stdin, stdout): + inputs = [int(item.strip()) for item in stdin.read().strip().split(' ') if item] + _correct_sum = sum(inputs) + + outputs = stdout.read().strip().split(' ', maxsplit=2) + if len(outputs) >= 1: + _result = int(outputs[0]) + else: + return False, 'No output found.' + + if _result == _correct_sum: + return True, 'Correct result.', 'Oh yeah, well done ^_^.' + else: + return False, 'Result {correct} expected but {actual} found.'.format( + correct=repr(_correct_sum), actual=repr(_result) + ) + + +if __name__ == '__main__': + pyspj_entry( + 'demo_pyspj', spj_func, + version='2.3.3', # optional + author='spj-dev', # optional + email='spj-demo@my-email.com', # optional + )() diff --git a/docs/source/tutorials/advanced_usage/spj_runnable_help.demo.sh b/docs/source/tutorials/advanced_usage/spj_runnable_help.demo.sh new file mode 100644 index 0000000..5169419 --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_runnable_help.demo.sh @@ -0,0 +1 @@ +python spj_runnable.py -h \ No newline at end of file diff --git a/docs/source/tutorials/advanced_usage/spj_runnable_installer.sh b/docs/source/tutorials/advanced_usage/spj_runnable_installer.sh new file mode 100644 index 0000000..9612f64 --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_runnable_installer.sh @@ -0,0 +1 @@ +pyinstaller -D -F -n demo_spj -c spj_runnable.py \ No newline at end of file diff --git a/docs/source/tutorials/advanced_usage/spj_runnable_version.demo.sh b/docs/source/tutorials/advanced_usage/spj_runnable_version.demo.sh new file mode 100644 index 0000000..fecb307 --- /dev/null +++ b/docs/source/tutorials/advanced_usage/spj_runnable_version.demo.sh @@ -0,0 +1 @@ +python spj_runnable.py -v \ No newline at end of file diff --git a/requirements-doc.txt b/requirements-doc.txt index 2d82e1f..0dc3d81 100644 --- a/requirements-doc.txt +++ b/requirements-doc.txt @@ -7,3 +7,4 @@ packaging sphinx-multiversion~=0.2.4 where~=1.0.2 easydict>=1.7,<2 +pyinstaller>=4.7,<5