doc(usage): add documentation for advanced usage

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

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:
+

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

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= '

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=,'

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

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

docs/source/tutorials/advanced_usage/spj_continuity_demo_2.demo.sh

@@ -0,0 +1 @@
+pyspj -i '15' -o '7 8' -s spj_continuity -p

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

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
+    )()

docs/source/tutorials/advanced_usage/spj_runnable_help.demo.sh

@@ -0,0 +1 @@
+python spj_runnable.py -h

docs/source/tutorials/advanced_usage/spj_runnable_installer.sh

@@ -0,0 +1 @@
+pyinstaller -D -F -n demo_spj -c spj_runnable.py

docs/source/tutorials/advanced_usage/spj_runnable_version.demo.sh

@@ -0,0 +1 @@
+python spj_runnable.py -v

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