Merge pull request #152 from traP-jp/docs/#145-traopy-docstrings

📝 add docs for traopy

Author: comavius

pylib/traopy/python/traopy/lowlevel.pyi

@@ -8,53 +8,113 @@ import typing
 from enum import Enum, auto
 
 class Dependency:
+    r"""
+    Dependency object to refer to previous output.
+    
+    Path to the output will be provided as an environment variable named `envvar_name`.
+    """
     def __new__(cls,ref_to:Output, envvar_name:builtins.str): ...
     ...
 
 class EmptyDirectory:
+    r"""
+    Empty directory object to be placed in the execution environment.
+    """
     def __new__(cls,name:builtins.str): ...
     ...
 
 class Execution:
+    r"""
+    Execution object to be executed
+    
+    Script will be run with paths as environment variables specified in `depends_on`.
+    """
     def __new__(cls,name:builtins.str, script:ScriptOutput, depends_on:typing.Sequence[Dependency]): ...
     ...
 
 class LocalJudge:
+    r"""
+    LocalJudge object to run provided procedures in your local environment.
+    """
     def __new__(cls,temp_dir:builtins.str | os.PathLike | pathlib.Path): ...
     def run(self, builder:ProcedureBuilder, runtime_text_contents:typing.Mapping[builtins.str, builtins.str]) -> builtins.str:
+        r"""
+        Run the provided procedure in your local environment.
+        """
         ...
 
 
 class Output:
+    r"""
+    Output object of each job.
+    
+    Executions can depend on Output by passing Output object to `depends_on` field of Execution.
+    """
     ...
 
 class ProcedureBuilder:
+    r"""
+    ProcedureBuilder object to build a procedure.
+    """
     def __new__(cls,): ...
     def add_resource(self, resource:ResourceKind) -> Output:
+        r"""
+        Add a resource to the procedure.
+        """
         ...
 
     def add_script(self, script:Text) -> ScriptOutput:
+        r"""
+        Add a script to the procedure.
+        """
         ...
 
     def add_execution(self, execution:Execution) -> Output:
+        r"""
+        Add an execution to the procedure.
+        """
         ...
 
     def write_to(self, path:builtins.str | os.PathLike | pathlib.Path) -> None:
+        r"""
+        Export the procedure to a json file.
+        """
         ...
 
 
 class RuntimeText:
+    r"""
+    RuntimeText object to be placed in the execution environment.
+    
+    `label`s have corresponding types of resources determined in judge-run time.
+    | label | description |
+    | --- | --- |
+    | `source` | Submission source code |
+    | `time_limit` | Time limit(optional) |
+    | `memory_limit` | Memory limit(optional) |
+    | `language` | Language of the submission(optional) |
+    """
     def __new__(cls,name:builtins.str, label:builtins.str): ...
     ...
 
 class ScriptOutput:
     ...
 
 class Text:
+    r"""
+    Text object to be placed in the execution environment.
+    
+    Contents of Text must be static.
+    """
     def __new__(cls,name:builtins.str, path:builtins.str | os.PathLike | pathlib.Path): ...
     ...
 
 class ResourceKind(Enum):
+    r"""
+    Resource object to be placed in the execution environment.
+    
+    EmptyDirectory is an directory and TextFile and RuntimeTextFile are files.
+    """
     EmptyDirectory = auto()
     RuntimeTextFile = auto()
     TextFile = auto()

pylib/traopy/src/local_judge.rs

@@ -11,6 +11,7 @@ use pyo3_stub_gen::derive::*;
 use std::collections::HashMap;
 use std::path::PathBuf;
 
+/// LocalJudge object to run provided procedures in your local environment.
 #[gen_stub_pyclass]
 #[pyclass]
 pub struct LocalJudge {
@@ -31,6 +32,7 @@ impl LocalJudge {
         }
     }
 
+    /// Run the provided procedure in your local environment.
     #[pyo3(name = "run")]
     async fn run(
         &self,

pylib/traopy/src/models/dependency.rs

@@ -3,6 +3,9 @@ use judge_core::procedure::writer_schema::Dependency;
 use pyo3::prelude::*;
 use pyo3_stub_gen::derive::*;
 
+/// Dependency object to refer to previous output.
+///
+/// Path to the output will be provided as an environment variable named `envvar_name`.
 #[gen_stub_pyclass]
 #[pyclass]
 #[pyo3(name = "Dependency")]

pylib/traopy/src/models/empty_directory.rs

@@ -2,6 +2,7 @@ use judge_core::procedure::writer_schema::EmptyDirectory;
 use pyo3::prelude::*;
 use pyo3_stub_gen::derive::*;
 
+/// Empty directory object to be placed in the execution environment.
 #[gen_stub_pyclass]
 #[pyclass]
 #[pyo3(name = "EmptyDirectory")]

pylib/traopy/src/models/execution.rs

@@ -3,6 +3,9 @@ use judge_core::procedure::writer_schema::{Dependency, Execution};
 use pyo3::prelude::*;
 use pyo3_stub_gen::derive::*;
 
+/// Execution object to be executed
+///
+/// Script will be run with paths as environment variables specified in `depends_on`.
 #[gen_stub_pyclass]
 #[pyclass]
 #[pyo3(name = "Execution")]

pylib/traopy/src/models/output.rs

@@ -1,6 +1,9 @@
 use pyo3::prelude::*;
 use pyo3_stub_gen::derive::*;
 
+/// Output object of each job.
+///
+/// Executions can depend on Output by passing Output object to `depends_on` field of Execution.
 #[gen_stub_pyclass]
 #[pyclass]
 #[pyo3(name = "Output")]

pylib/traopy/src/models/resource_kind.rs

@@ -3,6 +3,9 @@ use judge_core::procedure::writer_schema::ResourceKind;
 use pyo3::prelude::*;
 use pyo3_stub_gen::derive::*;
 
+/// Resource object to be placed in the execution environment.
+///
+/// EmptyDirectory is an directory and TextFile and RuntimeTextFile are files.
 #[gen_stub_pyclass_enum]
 #[pyclass]
 #[pyo3(name = "ResourceKind")]

pylib/traopy/src/models/runtime_text.rs

@@ -2,6 +2,15 @@ use judge_core::procedure::writer_schema::RuntimeText;
 use pyo3::prelude::*;
 use pyo3_stub_gen::derive::*;
 
+/// RuntimeText object to be placed in the execution environment.
+///
+/// `label`s have corresponding types of resources determined in judge-run time.
+/// | label | description |
+/// | --- | --- |
+/// | `source` | Submission source code |
+/// | `time_limit` | Time limit(optional) |
+/// | `memory_limit` | Memory limit(optional) |
+/// | `language` | Language of the submission(optional) |
 #[gen_stub_pyclass]
 #[pyclass]
 #[pyo3(name = "RuntimeText")]

pylib/traopy/src/models/text.rs

@@ -3,6 +3,9 @@ use pyo3::prelude::*;
 use pyo3_stub_gen::derive::*;
 use std::path::PathBuf;
 
+/// Text object to be placed in the execution environment.
+///
+/// Contents of Text must be static.
 #[gen_stub_pyclass]
 #[pyclass]
 #[pyo3(name = "Text")]

pylib/traopy/src/procedure_builder.rs

@@ -5,6 +5,7 @@ use pyo3::prelude::*;
 use pyo3_stub_gen::derive::*;
 use std::path::PathBuf;
 
+/// ProcedureBuilder object to build a procedure.
 #[gen_stub_pyclass]
 #[pyclass]
 #[pyo3(name = "ProcedureBuilder")]
@@ -23,6 +24,7 @@ impl PyProcedureBuilder {
         }
     }
 
+    /// Add a resource to the procedure.
     #[pyo3(name = "add_resource")]
     fn add_resource(&mut self, resource: resource_kind::PyResourceKind) -> output::PyOutput {
         let schema_resource = writer_schema::ResourceKind::from(resource);
@@ -31,6 +33,7 @@ impl PyProcedureBuilder {
         output
     }
 
+    /// Add a script to the procedure.
     #[pyo3(name = "add_script")]
     fn add_script(&mut self, script: text::PyText) -> output::PyScriptOutput {
         let schema_script = writer_schema::Text::from(script);
@@ -39,6 +42,7 @@ impl PyProcedureBuilder {
         output
     }
 
+    /// Add an execution to the procedure.
     #[pyo3(name = "add_execution")]
     fn add_execution(&mut self, execution: execution::PyExecution) -> output::PyOutput {
         let script_name = execution.script.name.clone();
@@ -56,6 +60,7 @@ impl PyProcedureBuilder {
         output
     }
 
+    /// Export the procedure to a json file.
     #[pyo3(name = "write_to")]
     fn write_to(&self, path: PathBuf) -> () {
         // output this instance as a json file