chore: update docs

.pre-commit-config.yaml

@@ -35,4 +35,5 @@ repos:
   rev: v0.4.10
   hooks:
   - id: ruff
+    args: [--fix]
     stages: [pre-commit]

CHANGELOG.md

@@ -169,4 +169,3 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [v0.0.1](https://github.com/DataShades/ckanext-files/releases/tag/v0.0.1) - 2021-09-21
 
 <small>[Compare with first commit](https://github.com/DataShades/ckanext-files/compare/d57d17e412821d56a9f5262636be89311e8050fc...v0.0.1)</small>
-

Makefile

@@ -8,8 +8,10 @@ help:
 changelog:  ## compile changelog
 	git changelog -c conventional -o CHANGELOG.md $(if $(bump),-B $(bump))
 
+deploy-docs:  ## build and publish documentation
+	mkdocs gh-deploy
 
-test-server:
+test-server:  ## start server for frontend testing
 	yes | ckan -c test.ini db clean
 	ckan -c test.ini db upgrade
 	yes | ckan -ctest.ini sysadmin add admin password=password123 email=admin@test.net

ckanext/files/base.py

@@ -83,11 +83,33 @@ def into_model(self, record: TFileModel):
 
 @dataclasses.dataclass
 class FileData(BaseData[model.File]):
+    """Information required by storage to operate the file.
+
+    Example:
+    >>> FileData(
+    >>>     "local/path.txt",
+    >>>     123,
+    >>>     "text/plain",
+    >>>     md5_of_content,
+    >>> )
+    """
+
     content_type: str = "application/octet-stream"
 
 
 @dataclasses.dataclass
 class MultipartData(BaseData[model.Multipart]):
+    """Information required by storage to operate the incomplete upload.
+
+    Example:
+    >>> FileData(
+    >>>     "local/path.txt",
+    >>>     expected_size,
+    >>>     expected_content_type,
+    >>>     expected_hash,
+    >>> )
+    """
+
     location: str = ""
 
 
@@ -233,6 +255,8 @@ def multipart_complete(
 
 
 class Manager(StorageService):
+    """Service responsible for maintenance file operations."""
+
     def remove(self, data: FileData | MultipartData, extras: dict[str, Any]) -> bool:
         """Remove file from the storage."""
         raise NotImplementedError
@@ -289,6 +313,8 @@ def analyze(self, location: str, extras: dict[str, Any]) -> FileData:
 
 
 class Reader(StorageService):
+    """Service responsible for reading data from the storage."""
+
     def stream(self, data: FileData, extras: dict[str, Any]) -> Iterable[bytes]:
         """Return byte-stream of the file content."""
         raise NotImplementedError
@@ -347,6 +373,8 @@ def public_link(self, data: FileData, extras: dict[str, Any]) -> str:
 
 
 class Storage(OptionChecker, abc.ABC):
+    """Base class for storage implementation."""
+
     hidden = False
     capabilities = utils.Capability.NONE
 

ckanext/files/cli/__init__.py

@@ -33,9 +33,9 @@ def files():
 
 @files.command()
 @click.argument("file_id")
-@click.option("--start", type=int, default=0)
-@click.option("--end", type=int)
-@click.option("-o", "--output")
+@click.option("--start", type=int, default=0, help="Start streaming from position")
+@click.option("--end", type=int, help="End streaming at position")
+@click.option("-o", "--output", help="Stream into specified file or directory")
 def stream(file_id: str, output: str | None, start: int, end: int | None):
     """Stream content of the file."""
 

ckanext/files/cli/dev.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+import enum
 import inspect
 import pydoc
+from types import ModuleType
 from typing import Any, Callable
 
 import click
@@ -28,7 +30,11 @@ def api_docs():
     for name, func in actions:
         if not name.startswith("files_"):
             continue
-        _doc_function(func)
+
+        if name in ["files_file_search_by_user"]:
+            continue
+
+        _doc_action(func)
 
 
 @group.command()
@@ -43,32 +49,83 @@ def shared_docs():
     )
     for name in shared.__all__:
         el = getattr(shared, name)
+
         if inspect.isfunction(el):
             _doc_function(el)
 
+        elif inspect.isclass(el):
+            _doc_class(el)
+
+        elif inspect.ismodule(el):
+            _doc_module(name, el)
+
+
+def _doc_action(func: Callable[..., Any]):
+    click.echo(f"## {func.__name__}\n")
+
+    for line in _mdize_doc(func):
+        click.echo(line)
+
+    click.echo("\n")
+
 
 def _doc_function(func: Callable[..., Any]):
-    click.echo(f"## `{func.__name__}{inspect.signature(func)}`\n")
+    click.echo(f"## {func.__name__}\n")
+
+    signature = str(inspect.signature(func)).replace("'", "")
+    click.echo(f"Signature: `{signature}`\n")
 
     for line in _mdize_doc(func):
         click.echo(line)
 
     click.echo("\n")
 
 
+def _doc_class(cls: type):
+    click.echo(f"## {cls.__name__}\n")
+    signature = inspect.signature(cls)
+
+    if signature.parameters and not issubclass(cls, enum.Enum):
+        clean_signature = str(signature).replace("''", '""').replace("'", "")
+        click.echo(f"Signature: `{clean_signature}`\n")
+
+    for line in _mdize_doc(cls):
+        click.echo(line)
+
+    click.echo("\n")
+
+
+def _doc_module(name: str, module: ModuleType):
+
+    click.echo(f"## {name} ({module.__name__} module)\n")
+
+    for line in _mdize_doc(module):
+        click.echo(line)
+
+    click.echo("\n")
+
+
 def _mdize_doc(item: Any):
     lines = pydoc.getdoc(item).splitlines()
     in_code_block = False
+    indent = ""
+
     for line in lines:
+        if line == "Example:":
+            yield "!!! example"
+            indent = "\t"
+            continue
+
         if line.startswith(">>> ") and not in_code_block:
             in_code_block = True
-            yield "```python"
+            yield indent + "```python"
 
         if not line.startswith(">>>") and in_code_block:
+            yield indent + "```"
             in_code_block = False
-            yield "```"
+            indent = ""
 
-        yield line[4 if in_code_block else 0 :]
+        yield indent + line[4 if in_code_block else 0 :]
 
     if in_code_block:
-        yield "```"
+        yield indent + "```"

ckanext/files/cli/maintain.py

@@ -95,14 +95,8 @@ def invalid_owner(storage_name: str | None, remove: bool):
     for file in files:
         size = utils.humanize_filesize(file.size)
         click.echo(
-            "\t{}: {} [{}, {}]. Owner: {} {}".format(
-                file.id,
-                file.name,
-                file.content_type,
-                size,
-                file.owner_info.owner_type,
-                file.owner_info.owner_id,
-            ),
+            f"\t{file.id}: {file.name} [{file.content_type}, {size}]. "
+            + f"Owner: {file.owner_info.owner_type} {file.owner_info.owner_id}",
         )
 
     if remove and click.confirm("Do you want to delete these files?"):
@@ -117,7 +111,7 @@ def invalid_owner(storage_name: str | None, remove: bool):
 @storage_option
 @click.option("--remove", is_flag=True, help="Remove files")
 def missing_files(storage_name: str | None, remove: bool):
-    """Manage files do not exist in storage."""
+    """Manage files that do not exist in storage."""
     storage_name = storage_name or shared.config.default_storage()
     try:
         storage = shared.get_storage(storage_name)