Commit 73ebdf24 authored by Eckhart Arnold's avatar Eckhart Arnold
Browse files

some docstrings adjusted for reStructuredText

parent 212db588
......@@ -288,22 +288,21 @@ def compile_source(source: str,
no fatal errors occurred in any of the earlier stages of the processing
pipeline.
Args:
source (str): The input text for compilation or a the name of a
:param source (str): The input text for compilation or a the name of a
file containing the input text.
preprocessor (function): text -> text. A preprocessor function
:param preprocessor (function): text -> text. A preprocessor function
or None, if no preprocessor is needed.
parser (function): A parsing function or grammar class
transformer (function): A transformation function that takes
:param parser (function): A parsing function or grammar class
:param transformer (function): A transformation function that takes
the root-node of the concrete syntax tree as an argument and
transforms it (in place) into an abstract syntax tree.
compiler (function): A compiler function or compiler class
:param compiler (function): A compiler function or compiler class
instance
preserve_AST (bool): Preserves the AST-tree.
:param preserve_AST (bool): Preserves the AST-tree.
Returns (tuple):
The result of the compilation as a 3-tuple
:return: The result of the compilation as a 3-tuple
(result, errors, abstract syntax tree). In detail:
1. The result as returned by the compiler or ``None`` in case of failure
2. A list of error or warning messages
3. The root-node of the abstract syntax tree if `preserve_ast` is True
......
......@@ -350,15 +350,14 @@ class ExecutionEnvironment:
"""Class ExecutionEnvironment provides methods for executing server tasks
in separate processes, threads, as asynchronous task or as simple function.
Attributes:
process_executor: A process-pool-executor for cpu-bound tasks
thread_executor: A thread-pool-executor for blocking tasks
loop: The asynchronous event loop for running coroutines
log_file: The name of the log-file to which error messages
are written if an executor raises a Broken-Error.
_closed A Flag that is set to True after the `shutdown()`-
method has been called. After that any
call to the `execute()`-method yields an error.
:var process_executor: A process-pool-executor for cpu-bound tasks
:var thread_executor: A thread-pool-executor for blocking tasks
:var loop: The asynchronous event loop for running coroutines
:var log_file: The name of the log-file to which error messages are
written if an executor raises a Broken-Error.
:var _closed: A Flag that is set to True after the `shutdown-method
has been called. After that any call to the `execute()`-method
yields an error.
"""
def __init__(self, event_loop: asyncio.AbstractEventLoop):
self.process_executor = ProcessPoolExecutor() # type: Optional[ProcessPoolExecutor]
......@@ -375,10 +374,10 @@ class ExecutionEnvironment:
params: Union[Dict, Sequence])\
-> Tuple[Optional[JSON_Type], Optional[RPC_Error_Type]]:
"""Executes a method with the given parameters in a given executor
(`ThreadPoolExcecutor` or `ProcessPoolExecutor`). `execute()`waits for
the completion and returns the JSON result and an RPC error tuple (see
(``ThreadPoolExcecutor`` or ``ProcessPoolExecutor``). ``execute()`` waits
for the completion and returns the JSON result and an RPC error tuple (see
the type definition above). The result may be None and the error may be
zero, i.e. no error. If `executor` is `None`the method will be called
zero, i.e. no error. If `executor` is `None` the method will be called
directly instead of deferring it to an executor.
"""
if self._closed:
......@@ -733,48 +732,48 @@ class Server:
LSP-functionality via the rpc_functions-parameter to the
constructor of this class.
:ivar server_name: A name for the server. Defaults to
:var server_name: A name for the server. Defaults to
`CLASSNAME_OBJECTID`
:ivar strict_lsp: Enforce Language-Server-Protocol von json-rpc-calls.
:var strict_lsp: Enforce Language-Server-Protocol von json-rpc-calls.
If `False` json-rpc calls will be processed even without prior
initialization, just like plain data or http calls.
:ivar cpu_bound: Set of function names of functions that are cpu-bound
:var cpu_bound: Set of function names of functions that are cpu-bound
and will be run in separate processes.
:ivar blocking: Set of functions that contain blocking calls
:var blocking: Set of functions that contain blocking calls
(e.g. IO-calls) and will therefore be run in separate threads.
:ivar rpc_table: Table mapping LSP-method names to Python functions
:ivar known_methods: Set of all known LSP-methods. This includes the
:var rpc_table: Table mapping LSP-method names to Python functions
:var known_methods: Set of all known LSP-methods. This includes the
methods in the rpc-table and the four initialization methods,
`initialize()`, `initialized()`, `shutdown()`, `exit`
:ivar connection_callback: A callback function that is called with the
:var connection_callback: A callback function that is called with the
connection object as argument when a connection to a client is
established
:ivar max_data_size: Maximal size of a data chunk that can be read by
:var max_data_size: Maximal size of a data chunk that can be read by
the server at a time.
:ivar stage: The operation stage, the server is in. Can be on of the four
:var stage: The operation stage, the server is in. Can be on of the four
values: `SERVER_OFFLINE`, `SERVER_STARTING`, `SERVER_ONLINE`,
`SERVER_TERMINATING`
:ivar host: The host, the server runs on, e.g. "127.0.0.1"
:ivar port: The port of the server, e.g. 8888
:ivar server: The asyncio.Server if the server is online, or `None`.
:ivar serving_task: The task in which the asyncio.Server is run.
:ivar stop_response: The response string that is written to the stream
:var host: The host, the server runs on, e.g. "127.0.0.1"
:var port: The port of the server, e.g. 8888
:var server: The asyncio.Server if the server is online, or `None`.
:var serving_task: The task in which the asyncio.Server is run.
:var stop_response: The response string that is written to the stream
as answer to a stop request.
:ivar echo_log: Read from the global configuration. If True, any log
:var echo_log: Read from the global configuration. If True, any log
message will also be echoed on the console.
:ivar log_file: The file-name of the server-log.
:ivar use_jsonrpc_header: Read from the global configuration. If True,
:var log_file: The file-name of the server-log.
:var use_jsonrpc_header: Read from the global configuration. If True,
jsonrpc-calls or responses will always be preceeded by a simple header
of the form: "Content-Length: {NUM}\n\n", where "{NUM}" stands for
the byte-size of the rpc-package.
:ivar exec: An instance of the execution environment that delegates tasks
of the form: `Content-Length: {NUM}\\n\\n`, where `{NUM}`
stands for the byte-size of the rpc-package.
:var exec: An instance of the execution environment that delegates tasks
to separate processes, threads, asynchronous tasks or simple function
calls.
:ivar connection: An instance of the connection class representing the
:var connection: An instance of the connection class representing the
data of the current connection or None, if there is no connection at
the moment. There can be only one connection to the server at a time!
:ivar kill_switch: If True the, the server will be shut down.
:ivar loop: The asyncio event loop within which the asyncio stream server
:var kill_switch: If True the, the server will be shut down.
:var loop: The asyncio event loop within which the asyncio stream server
is run.
"""
def __init__(self, rpc_functions: RPC_Type,
......@@ -1551,6 +1550,7 @@ def spawn_tcp_server(host: str = USE_DEFAULT_HOST,
Starts DHParser-Server that communicates via tcp in a separate process.
Can be used for writing test code. WARNING: Does not seem to work with
multiprocessing.set_start_method('spawn')` under linux !?
:param host: The host for the tcp-communication, e.g. 127.0.0.1
:param port: the port number for the tcp-communication.
:param parameters: The parameter-tuple for initializing the server or
......@@ -1586,6 +1586,7 @@ def spawn_stream_server(reader: StreamReaderType,
"""
Starts a DHParser-Server that communitcates via streams in a separate
process.
:param reader: The stream from which the server will read requests.
:param writer: The stram to which the server will write responses.
:param parameters: The parameter-tuple for initializing the server or
......
......@@ -418,10 +418,10 @@ class TextBuffer:
@cython.locals(version=cython.int)
def text_edits(self, edits: Union[list, dict], version: int = -1):
"""Incorporates the one or more text-edits or change-events into the text.
A Text-Edit is a dictionary of this form:
A Text-Edit is a dictionary of this form::
{"range": {"start": {"line": 0, "character": 0 },
"end": {"line": 0, "character": 0} },
"end": {"line": 0, "character": 0 } },
"newText": "..."}
In case of a change-event, the key "newText" is replaced by "text".
......@@ -448,7 +448,7 @@ class TextBuffer:
def snapshot(self, eol: str = '\n') -> Union[str, StringView]:
"""Returns the current state of the entire text, using the given
end of line marker ('\n' or '\r\n')"""
end of line marker (``\\n`` or ``\\r\\n``)"""
if self._text:
return self._text
self._text = eol.join(str(line) for line in self._buffer)
......
......@@ -1225,11 +1225,11 @@ class Node: # (collections.abc.Sized): Base class omitted for cython-compatibil
empty_tags: Set[str] = set()) -> str:
"""Returns content as XML-tree.
:param src: The source text or `None`. In case the source text is given,
the position will also be reported as line and column.
:param src: The source text or `None`. In case the source text is
given, the position will also be reported as line and column.
:param indentation: The number of whitespaces for indentation
:param inline_tags: A set of tag names, the content of which will always be written
on a single line, unless it contains explicit line feeds ('\n').
:param inline_tags: A set of tag names, the content of which will always be
written on a single line, unless it contains explicit line feeds (`\\n`).
:param omit_tags: A set of tags from which only the content will be printed, but
neither the opening tag nor its attr nor the closing tag. This
allows producing a mix of plain text and child tags in the output,
......
......@@ -1480,10 +1480,9 @@ def insert(context: List[Node], position: PositionType, node_factory: Callable):
or equal the number of children mean that the delimiter will be appended
to the tuple of children.
Example:
insert(pos_of('paragraph'), node_maker('LF', '\n'))
Example::
insert(pos_of('paragraph'), node_maker('LF', '\\n'))
"""
pos_tuple = normalize_position_representation(context, position)
if not pos_tuple:
......
......@@ -13,6 +13,7 @@
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import re
import sys
sys.path.insert(0, os.path.abspath('../'))
sys.path.insert(0, os.path.abspath('../DHParser'))
......@@ -27,9 +28,10 @@ copyright = '2018, Eckhart Arnold'
author = 'Eckhart Arnold'
# The short X.Y version
version = ''
from DHParser import versionnumber
version = re.match('\d+\.\d+(?:\.\d+)?', versionnumber.__version__).group(0)
# The full version, including alpha/beta/rc tags
release = '0.8'
release = versionnumber.__version__
# -- General configuration ---------------------------------------------------
......@@ -71,7 +73,7 @@ master_doc = 'index'
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
......@@ -90,7 +92,7 @@ add_module_names = False
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
html_theme = 'alabaster' # 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
......@@ -106,7 +108,7 @@ html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_static_path = ['html_assets']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment