make docstrings more concise

Author: elfkuzco

libzim/libzim.pyx

@@ -284,7 +284,7 @@ cdef class _Creator:
         pass
 
     def config_verbose(self, bool verbose: bool) -> Creator:
-        """Set creator verbosity (inside libzim). Default is off.
+        """Set creator verbosity inside libzim (default: off).
 
         Args:
             verbose (bool): Whether to enable verbosity.
@@ -348,7 +348,7 @@ cdef class _Creator:
         return self
 
     def config_nbworkers(self, int nbWorkers: pyint) -> Creator:
-        """Configures the number of threads to use for internal workers.
+        """Configures the number of threads to use for internal workers (default: 4).
 
         Args:
             nbWorkers (int): The number of threads to allocate.
@@ -379,11 +379,11 @@ cdef class _Creator:
         Refer to https://wiki.openzim.org/wiki/Metadata for more details.
 
         Args:
-            size (int): The size of the illustration in bytes.
+            size (int): The width of the square PNG illustration in pixels.
             content (bytes): The binary content of the PNG illustration.
 
         Raises:
-            RuntimeError: If an illustration with the same size already exists.
+            RuntimeError: If an illustration with the same width already exists.
         """
         cdef string _content = content
         self.c_creator.addIllustration(size, _content)
@@ -496,7 +496,7 @@ cdef class _Creator:
 
     @property
     def filename(self) -> pathlib.Path:
-        """pathlib.Path: Path of the ZIM Archive."""
+        """pathlib.Path: Path of the ZIM Archive on the filesystem."""
         return self._filename
 
 class ContentProvider:
@@ -581,7 +581,7 @@ class FileProvider(ContentProvider):
 class IndexData:
     """IndexData stub to override.
 
-    Return a subclass of it in `Item.get_indexdata()`.
+    A subclass of it should be returned in `Item.get_indexdata()`.
     """
     __module__ = writer_module_name
 
@@ -596,7 +596,7 @@ class IndexData:
     def get_title(self) -> str:
         """Get the title to use when indexing an Item.
 
-        Might be the same as `Item.get_title` or not.
+        Might be the same as Item's title or not.
 
         Returns:
             str: The title to use.
@@ -606,7 +606,7 @@ class IndexData:
     def get_content(self) -> str:
         """Get the content to use when indexing an Item.
 
-        Might be the same as Item.get_title or not.
+        Might be the same as Item's content or not.
 
         Returns:
             str: The content to use.
@@ -617,14 +617,15 @@ class IndexData:
         """Get the keywords used to index the item.
 
         Returns:
-            Must be a string containing keywords separated by a space"""
+            Space-separated string containing keywords to index for.
+        """
         raise NotImplementedError("get_keywords must be implemented.")
 
     def get_wordcount(self) -> int:
         """Get the number of word in content.
 
         Returns:
-            The number of words in the item.
+            Number of words in the item's content.
         """
 
         raise NotImplementedError("get_wordcount must be implemented.")
@@ -633,7 +634,8 @@ class IndexData:
         """GeoPosition used to index the item.
 
         Returns:
-            Must be a tuple (latitude, longitude) or None"""
+            A (latitude, longitude) tuple or None.
+        """
 
         return None
 
@@ -656,23 +658,23 @@ class BaseWritingItem:
         The path must be absolute and unique.
 
         Returns:
-            The path of the item.
+            Path of the item.
         """
         raise NotImplementedError("get_path must be implemented.")
 
     def get_title(self) -> str:
         """Item title. Might be indexed and used in suggestions.
 
         Returns:
-            The title of the item.
+            Title of the item.
         """
         raise NotImplementedError("get_title must be implemented.")
 
     def get_mimetype(self) -> str:
         """MIME-type of the item's content.
 
         Returns:
-            The mimetype of the item.
+            Mimetype of the item.
         """
         raise NotImplementedError("get_mimetype must be implemented.")
 
@@ -687,8 +689,10 @@ class BaseWritingItem:
     def get_hints(self) -> Dict[Hint, pyint]:
         """Get the Hints that help the Creator decide how to handle this item.
 
+        Hints affects compression, presence in suggestion, random and search.
+
         Returns:
-            Hints to help the Creator decided how to handle this item.
+            Hints to help the Creator decide how to handle this item.
         """
         raise NotImplementedError("get_hints must be implemented.")
 
@@ -826,7 +830,7 @@ cdef class Entry:
         """Creates a python Entry from a C++ Entry (zim::).
 
         Args:
-        ent (Entry): (A C++ Entry
+        ent (Entry): A C++ Entry
 
         Returns:
             Entry: Casted entry

mkdocs.yml

@@ -87,8 +87,6 @@ plugins:
             - https://typing-extensions.readthedocs.io/en/latest/objects.inv
           options:
             heading_level: 2
-            # Do not show the source code as python-libzim is just a wrapper
-            show_source: false
             load_external_modules: false
             show_submodules: false
             # force dynamic analysis from compiled module when loading data
@@ -101,7 +99,6 @@ plugins:
               - '!_module_'
               # *_public_objects for internal libzim-only vars that expose submodules
               - '!_public_objects$'
-            paths: [libzim]
             # List all inherited members without further filtering
             inherited_members: true
             # Put the signature in a code-block below the heading and modernize annotations

pyproject.toml

@@ -75,7 +75,7 @@ build = [
 ]
 docs = [
   "mkdocs==1.6.1",
-  "mkdocstrings[python]==0.27.0",
+  "mkdocstrings-python==1.14.5",
   "mkdocs-material==9.5.49",
   "pymdown-extensions==10.14",
   "mkdocs-gen-files==0.5.0",