Provide basic package-level documentation

protocol_code_generator/generate/code_generator.py

@@ -122,11 +122,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):

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)

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 *

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 *

src/eolib/encrypt/__init__.py

@@ -1,2 +1,6 @@
+"""
+Utilities to handle EO data encryption.
+"""
+
 from .encryption_utils import *
 from .server_verification_utils import *

src/eolib/packet/__init__.py

@@ -1,2 +1,6 @@
+"""
+Utilities for EO packets.
+"""
+
 from .sequence_start import *
 from .packet_sequencer import *

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 *

src/eolib/protocol/map/__init__.py

@@ -1 +1,8 @@
+"""
+EO map file data structures.
+
+See Also:
+  - [eolib.protocol._generated.map][]
+"""
+
 from .._generated.map import *

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 *

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 *

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 *

src/eolib/protocol/pub/__init__.py

@@ -1 +1,8 @@
+"""
+EO pub file data structures.
+
+See Also:
+  - [eolib.protocol._generated.pub][]
+"""
+
 from .._generated.pub import *