temp: Apply suggestions from code review

Co-authored-by: David Ormsbee <dave@axim.org>
Co-authored-by: Peter Pinch <pdpinch+github@hawklake.com>

Author: 3 people

source/developers/concepts/about_xblock_asides.rst

@@ -52,10 +52,8 @@ same way.
 
 Asides solve this by externalizing the enhancement. The host XBlock is not
 modified. The same aside can apply to a Video block, a Problem block, or any
-other block type, by overriding a single classmethod. Course authors keep
-control over whether the enhancement is active for a given block, because
-asides expose their own scoped fields. The enhancement travels with the
-course in OLX export and import.
+other block type, by overriding a single classmethod. Asides can serialize
+their own scoped fields during course import and export.
 
 Reach for an aside when all of the following are true:
 
@@ -70,9 +68,6 @@ Reach for an aside when all of the following are true:
 Reach for something else when:
 
 * You are creating a brand new piece of course content. Write an XBlock.
-* You need to change a behavior that is internal to a single block type and
-  not visible in any view. Consider a runtime service or a filter from the
-  Hooks Extension Framework.
 * You only need to react to platform events. Consider an Open edX event
   receiver.
 
@@ -83,15 +78,6 @@ The runtime maintains a many-to-many relationship between asides and host
 blocks at runtime, but each aside instance is bound to exactly one host block
 during a single render. The relationship is established in three stages.
 
-Discovery
-=========
-
-When the runtime renders an XBlock view, it asks the runtime for the set of
-applicable aside types. The default runtime returns every aside class
-registered through the ``xblock_asides.v1`` entry point. A runtime may
-override this to filter the set further, for example based on the current
-user or the course.
-
 Per-Block Filtering
 ===================
 
@@ -152,7 +138,7 @@ means an aside-enhanced course is portable, with limitations described below.
 Real-World Examples
 *******************
 
-Three implementations in the wild illustrate the range of what asides can
+Two implementations in the wild illustrate the range of what asides can
 do.
 
 Rapid Response XBlock
@@ -176,16 +162,6 @@ or a problem's siblings. A single aside class, registered as one entry
 point, handles both block types and uses ``should_apply_to_block`` to gate
 on a course-level waffle flag and per-course settings.
 
-Thumbs Sample Aside
-===================
-
-The `xblock-sdk`_ repository contains a ``ThumbsAside`` class in
-``sample_xblocks/thumbs/thumbs.py``. It is **not functional** and is not
-registered through any entry point. The class comment in the source notes:
-"Asides aren't ready yet, so this is currently not being installed in
-setup.py." It exists as a syntactic example of the decorator pattern, not
-as a working aside. Treat it as illustrative only.
-
 Limitations
 ***********
 
@@ -199,7 +175,7 @@ No Authoring Story in the Course Authoring MFE
 ==============================================
 
 The Studio author view for an aside is rendered by the legacy course
-authoring frontend. The current Course Authoring micro-frontend has no
+authoring frontend. The current Authoring micro-frontend has no
 defined location to display aside author UI. If your project depends on the
 new MFE for authoring, plan to render the aside's author UI through a
 different mechanism, or accept that authors will use the legacy Studio for
@@ -237,12 +213,12 @@ Documentation Has Historically Been Sparse
 ==========================================
 
 XBlock Asides have been part of the platform for years but have had no
-user-facing documentation until this set of articles. The original work was
-done by Dave Ormsbee. Most of the institutional knowledge has lived in
-docstrings, test code, and the implementations of a handful of asides
-maintained outside the core platform. If you find this documentation lacks
-detail your project needs, the test file at ``xblock/test/test_asides.py``
-in the XBlock repository is the most reliable source of behavioral truth.
+user-facing documentation until this set of articles. Most of the institutional
+knowledge has lived in docstrings, test code, and the implementations of a
+handful of asides maintained outside the core platform. If you find this
+documentation lacks detail your project needs, the test file at
+``xblock/test/test_asides.py`` in the XBlock repository is the most reliable
+source of behavioral truth.
 
 Where to Go Next
 ****************
@@ -253,7 +229,7 @@ and want a step-by-step recipe, read :ref:`Add an XBlock Aside`. For the
 complete list of classes, decorators, methods, and entry points, consult
 :ref:`XBlock Asides Reference`.
 
-.. _rapid-response-xblock: https://github.com/mitodl/rapid-response-xblock
+.. _rapid-response-xblock: https://github.com/mitodl/open-edx-plugins/tree/main/src/rapid_response_xblock
 .. _ol-openedx-chat: https://github.com/mitodl/open-edx-plugins/tree/main/src/ol_openedx_chat
 .. _xblock-sdk: https://github.com/openedx/xblock-sdk
 

source/developers/how-tos/add-an-xblock-aside.rst

@@ -6,7 +6,7 @@ Add an XBlock Aside
 
 .. tags:: developer, how-to
 
-Add an XBlock aside to attach behavior, UI, or stored data to one or more
+Add an XBlock Aside to attach behavior, UI, or stored data to one or more
 existing XBlock types without modifying those XBlocks. Use this recipe
 when you want a single, installable Python package that decorates the
 views of XBlocks in your platform.
@@ -227,16 +227,6 @@ Tutor:
    tutor mounts add /path/to/feedback_badge_aside
    tutor dev launch
 
-Or, if you are managing the environment manually:
-
-.. code-block:: bash
-
-   pip install -e /path/to/feedback_badge_aside
-
-After installing, restart both the LMS and Studio. Asides are discovered
-at process start, so newly installed asides do not appear until the
-services restart.
-
 Step 8: Enable asides in the LMS
 ********************************
 
@@ -293,7 +283,6 @@ If the aside does not appear:
 
 #. Check that ``should_apply_to_block`` returns ``True`` for the block
    you are testing.
-#. Check that the aside is allowlisted for the course.
 #. Check the LMS and Studio logs for any exceptions raised inside your
    aside view.
 

source/developers/quickstarts/quickstart_xblock_aside.rst

@@ -186,9 +186,6 @@ If the banner does not appear, work through these checks in order:
    The list should include ``hello_aside``. If it does not, the entry
    point is not installed; recheck Step 3 and Step 4.
 
-#. **The aside is allowlisted.** Confirm Step 5 was applied to the
-   course you are viewing.
-
 #. **The block type matches.** Your test block must have
    ``category == "problem"``. A Video block, an HTML block, or a
    Discussion block will not trigger the aside.