fix: doc lint issues

Author: navinkarkera

cms/djangoapps/contentstore/tests/test_upstream_downstream_links.py

@@ -60,6 +60,9 @@ def _create_unit(self, num: int):
         )
 
     def _create_unit_and_expected_container_link(self, course_key: str | CourseKey, num_blocks: int = 3):
+        """
+        Create unit xblock with random upstream key and version number.
+        """
         data = []
         for i in range(num_blocks):
             upstream, block = self._create_unit(i + 1)

cms/djangoapps/contentstore/utils.py

@@ -2375,6 +2375,9 @@ def get_xblock_render_context(request, block):
 
 
 def _create_or_update_component_link(course_key: CourseKey, created: datetime | None, xblock):
+    """
+    Create or update upstream->downstream link for components in database for given xblock.
+    """
     upstream_usage_key = UsageKeyV2.from_string(xblock.upstream)
     try:
         lib_component = get_component_from_usage_key(upstream_usage_key)
@@ -2394,6 +2397,9 @@ def _create_or_update_component_link(course_key: CourseKey, created: datetime |
 
 
 def _create_or_update_container_link(course_key: CourseKey, created: datetime | None, xblock):
+    """
+    Create or update upstream->downstream link for containers in database for given xblock.
+    """
     upstream_container_key = LibraryContainerLocator.from_string(xblock.upstream)
     try:
         lib_component = get_container_from_key(upstream_container_key)

cms/djangoapps/contentstore/xblock_storage_handlers/view_handlers.py

@@ -525,6 +525,10 @@ def create_item(request):
 
 
 def sync_library_content(created_block: XBlock, request, store, remove_upstream_link: bool = False):
+    """
+    Handle syncing library content for given xblock depending on its upstream type.
+    It can sync unit containers and lower level xblocks.
+    """
     upstream_key = check_and_parse_upstream_key(created_block.upstream, created_block.usage_key)
     if isinstance(upstream_key, LibraryUsageLocatorV2):
         lib_block = sync_from_upstream(downstream=created_block, user=request.user)

cms/lib/xblock/container_upstream_sync.py

@@ -1,3 +1,14 @@
+"""
+Synchronize content and settings from upstream containers to their downstream usages.
+
+* The upstream is a Container from a Learning Core-backed Content Library.
+* The downstream is a block of matching type in a SplitModuleStore-backed Course.
+* They are both on the same Open edX instance.
+
+HOWEVER, those assumptions may loosen in the future. So, we consider these to be INTERNAL ASSUMPIONS that should not be
+exposed through this module's public Python interface.
+"""
+
 import logging
 import typing as t
 from dataclasses import asdict, dataclass
@@ -120,6 +131,9 @@ def _get_library_container_url(container_key: LibraryContainerLocator):
 
 
 class ContainerUpstreamSyncManager(BaseUpstreamSyncManager):
+    """
+    Manages sync process of downstream containers like unit with upstream containers.
+    """
     def __init__(self, downstream: XBlock, user: User, upstream: XBlock | None = None) -> None:
         super().__init__(downstream, user, upstream)
         if not isinstance(self.upstream_key, LibraryContainerLocator):
@@ -152,7 +166,8 @@ def _load_upstream_link_and_container_block(self) -> XBlock:
 
         If `downstream` lacks a valid+supported upstream link, this raises an UpstreamLinkException.
         """
-        # We import load_block here b/c UpstreamSyncMixin is used by cms/envs, which loads before the djangoapps are ready.
+        # We import load_block here b/c UpstreamSyncMixin is used by cms/envs,
+        # which loads before the djangoapps are ready.
         from openedx.core.djangoapps.xblock.api import (  # pylint: disable=wrong-import-order
             CheckPerm,
             LatestVersion,
@@ -170,6 +185,9 @@ def _load_upstream_link_and_container_block(self) -> XBlock:
         return lib_block
 
     def sync_new_children_blocks(self):
+        """
+        Creates children xblocks in course based on library container children.
+        """
         for child in get_container_children(self.upstream_key, published=True):
             child_block = create_xblock(
                 parent_locator=str(self.downstream.location),

cms/lib/xblock/upstream_sync.py

@@ -11,6 +11,7 @@
 """
 from __future__ import annotations
 
+from abc import ABC
 import logging
 import typing as t
 from dataclasses import asdict, dataclass
@@ -186,7 +187,10 @@ def get_for_block(cls, downstream: XBlock) -> t.Self:
         )
 
 
-class BaseUpstreamSyncManager:
+class BaseUpstreamSyncManager(ABC):
+    """
+    Base manager class for managing upstream link sync process.
+    """
     def __init__(
         self,
         downstream: XBlock,
@@ -293,6 +297,9 @@ def sync(self) -> None:
 
 
 class ComponentUpstreamSyncManager(BaseUpstreamSyncManager):
+    """
+    Manages sync process of downstream component with upstream components.
+    """
     def __init__(self, downstream: XBlock, user: User, upstream: XBlock | None = None) -> None:
         super().__init__(downstream, user, upstream)
         if not upstream:
@@ -324,7 +331,8 @@ def _load_upstream_link_and_block(self) -> XBlock:
 
         If `downstream` lacks a valid+supported upstream link, this raises an UpstreamLinkException.
         """
-        # We import load_block here b/c UpstreamSyncMixin is used by cms/envs, which loads before the djangoapps are ready.
+        # We import load_block here b/c UpstreamSyncMixin is used by cms/envs,
+        # which loads before the djangoapps are ready.
         from openedx.core.djangoapps.xblock.api import (
             CheckPerm,
             LatestVersion,

openedx/core/djangoapps/content_libraries/library_context.py

@@ -42,7 +42,11 @@ def can_edit_block(self, user: UserType, usage_key: LibraryUsageLocatorV2 | Libr
         self._assert_key_instance(usage_key)
         return self._check_perm(user, usage_key.lib_key, permissions.CAN_EDIT_THIS_CONTENT_LIBRARY)
 
-    def can_view_block_for_editing(self, user: UserType, usage_key: LibraryUsageLocatorV2 | LibraryContainerLocator) -> bool:
+    def can_view_block_for_editing(
+        self,
+        user: UserType,
+        usage_key: LibraryUsageLocatorV2 | LibraryContainerLocator,
+    ) -> bool:
         """
         Assuming a block with the specified ID (usage_key) exists, does the
         specified user have permission to view its fields and OLX details (but
@@ -65,7 +69,7 @@ def can_view_block(self, user: UserType, usage_key: LibraryUsageLocatorV2 | Libr
         return self._check_perm(user, usage_key.lib_key, permissions.CAN_LEARN_FROM_THIS_CONTENT_LIBRARY)
 
     def _assert_key_instance(self, usage_key: LibraryUsageLocatorV2 | LibraryContainerLocator):
-        assert isinstance(usage_key, LibraryUsageLocatorV2) or isinstance(usage_key, LibraryContainerLocator)
+        assert isinstance(usage_key, (LibraryUsageLocatorV2, LibraryContainerLocator))
 
     def _check_perm(self, user: UserType, lib_key: LibraryLocatorV2, perm) -> bool:
         """ Helper method to check a permission for the various can_ methods"""