diff --git a/protocol_code_generator/generate/code_generator.py b/protocol_code_generator/generate/code_generator.py index 6dd6451..31c2fcc 100644 --- a/protocol_code_generator/generate/code_generator.py +++ b/protocol_code_generator/generate/code_generator.py @@ -121,11 +121,31 @@ def _generate_source_file(self, protocol_file): generated_init.add_import("*", absolute_package_path) - path = os.path.relpath(protocol_file.path, self._input_root) - path = os.path.join(os.path.dirname(path), "__init__.py") + relative_path = Path(os.path.relpath(protocol_file.path, self._input_root)).as_posix() + path = os.path.join(os.path.dirname(relative_path), "__init__.py") path = Path(path).as_posix() - generated_init_file = PythonFile(path, generated_init) + eo_protocol_url = "https://github.com/cirras/eo-protocol/tree/master/xml/" + relative_path + + public_package = os.path.join("eolib/protocol", relative_path) + public_package = os.path.dirname(public_package) + public_package = '.'.join(Path(public_package).parts) + + docstring = ( + CodeBlock() + .add_line('"""') + .add_line( + 'Data structures generated from the ' + + f'[eo-protocol]({eo_protocol_url}){{target="_blank"}} XML specification.' + ) + .add_line() + .add_line('Warning:') + .add_line(' - This subpackage should not be directly imported. ') + .add_line(f' - Instead, import [{public_package}][] (or the top-level `eolib`).') + .add_line('"""') + ) + + generated_init_file = PythonFile(path, generated_init, module_docstring=docstring) generated_init_file.write(self._output_root) def _generate_enum(self, protocol_enum): diff --git a/protocol_code_generator/generate/python_file.py b/protocol_code_generator/generate/python_file.py index 88cafd2..3f29236 100644 --- a/protocol_code_generator/generate/python_file.py +++ b/protocol_code_generator/generate/python_file.py @@ -5,9 +5,10 @@ class PythonFile: - def __init__(self, relative_path, code_block): + def __init__(self, relative_path, code_block, *, module_docstring=None): self._relative_path = relative_path self._code_block = code_block + self._module_docstring = module_docstring def write(self, root_path): output_path = os.path.join(root_path, self._relative_path) @@ -19,6 +20,10 @@ def write(self, root_path): header.add_line("# Changes will be lost when code is regenerated.") header.add_line() + if self._module_docstring is not None: + header.add_code_block(self._module_docstring) + header.add_line() + os.makedirs(os.path.dirname(output_path), exist_ok=True) package_path = os.path.dirname(self._relative_path) diff --git a/src/eolib/__init__.py b/src/eolib/__init__.py index 5c92c97..c5d2642 100644 --- a/src/eolib/__init__.py +++ b/src/eolib/__init__.py @@ -1,3 +1,7 @@ +""" +Top-level package that exports the whole EOLib API. +""" + from .data import * from .encrypt import * from .packet import * diff --git a/src/eolib/data/__init__.py b/src/eolib/data/__init__.py index 8fe5137..3fe1c60 100644 --- a/src/eolib/data/__init__.py +++ b/src/eolib/data/__init__.py @@ -1,3 +1,7 @@ +""" +Utilities to read and write EO data types. +""" + from .eo_numeric_limits import * from .number_encoding_utils import * diff --git a/src/eolib/encrypt/__init__.py b/src/eolib/encrypt/__init__.py index 663b41f..8d2ee91 100644 --- a/src/eolib/encrypt/__init__.py +++ b/src/eolib/encrypt/__init__.py @@ -1,2 +1,6 @@ +""" +Utilities to handle EO data encryption. +""" + from .encryption_utils import * from .server_verification_utils import * diff --git a/src/eolib/packet/__init__.py b/src/eolib/packet/__init__.py index 2f62b6f..b9640bf 100644 --- a/src/eolib/packet/__init__.py +++ b/src/eolib/packet/__init__.py @@ -1,2 +1,6 @@ +""" +Utilities for EO packets. +""" + from .sequence_start import * from .packet_sequencer import * diff --git a/src/eolib/protocol/__init__.py b/src/eolib/protocol/__init__.py index e60c906..c4782c9 100644 --- a/src/eolib/protocol/__init__.py +++ b/src/eolib/protocol/__init__.py @@ -1,3 +1,10 @@ +""" +EO protocol data structures. + +See Also: + - [eolib.protocol._generated][] +""" + from .serialization_error import * from .map import * diff --git a/src/eolib/protocol/map/__init__.py b/src/eolib/protocol/map/__init__.py index dd92956..4528cf1 100644 --- a/src/eolib/protocol/map/__init__.py +++ b/src/eolib/protocol/map/__init__.py @@ -1 +1,8 @@ +""" +EO map file data structures. + +See Also: + - [eolib.protocol._generated.map][] +""" + from .._generated.map import * diff --git a/src/eolib/protocol/net/__init__.py b/src/eolib/protocol/net/__init__.py index eb8e176..cddd20f 100644 --- a/src/eolib/protocol/net/__init__.py +++ b/src/eolib/protocol/net/__init__.py @@ -1,3 +1,10 @@ +""" +EO network protocol data structures. + +See Also: + - [eolib.protocol._generated.net][] +""" + from .packet import * from .client import * diff --git a/src/eolib/protocol/net/client/__init__.py b/src/eolib/protocol/net/client/__init__.py index 8ac351c..324b79e 100644 --- a/src/eolib/protocol/net/client/__init__.py +++ b/src/eolib/protocol/net/client/__init__.py @@ -1 +1,8 @@ +""" +EO network protocol data structures. + +See Also: + - [eolib.protocol._generated.net.client][] +""" + from ..._generated.net.client import * diff --git a/src/eolib/protocol/net/server/__init__.py b/src/eolib/protocol/net/server/__init__.py index 52e7619..ae6b169 100644 --- a/src/eolib/protocol/net/server/__init__.py +++ b/src/eolib/protocol/net/server/__init__.py @@ -1 +1,8 @@ +""" +EO network protocol data structures. + +See Also: + - [eolib.protocol._generated.net.server][] +""" + from ..._generated.net.server import * diff --git a/src/eolib/protocol/pub/__init__.py b/src/eolib/protocol/pub/__init__.py index 17a7fcc..74e7887 100644 --- a/src/eolib/protocol/pub/__init__.py +++ b/src/eolib/protocol/pub/__init__.py @@ -1 +1,8 @@ +""" +EO pub file data structures. + +See Also: + - [eolib.protocol._generated.pub][] +""" + from .._generated.pub import *