doc: frontend doc rework

- Add documentation for templatetags in page so we have full control over formatting.
  The autofunction solution doesn't work well for templatetags as it can't properly extract
  any arguments
- Add an overview page
- Put all API style docs under the API section
- Enhance the alliance_ui docs

docs/conf.py

@@ -89,7 +89,7 @@ def get_project_mapping(project_name: str):
         "https://docs.djangoproject.com/en/stable/",
         ("https://docs.djangoproject.com/en/stable/_objects/"),
     ),
-    "python": ("https://docs.python.org/3", "https://docs.python.org/3/objects.inv"),
+    "python": ("https://docs.python.org/3", None),
 }
 
 # Sphinx defaults to automatically resolve *unresolved* labels using all your Intersphinx mappings.
@@ -129,6 +129,12 @@ def setup(app):
         rolename="tfilter",
         indextemplate="pair: %s; template filter",
     )
+    # Allows usage of setting role, e.g. :setting:`FORM_RENDERER <django:FORM_RENDERER>`
+    app.add_crossref_type(
+        directivename="setting",
+        rolename="setting",
+        indextemplate="pair: %s; setting",
+    )
 
 
 generate_sidebar(current_dir, globals())

packages/ap-frontend/alliance_platform/frontend/templatetags/alliance_ui.py

@@ -5,6 +5,7 @@
 from allianceutils.auth.permission import reverse_if_probably_allowed
 from django import template
 from django.db.models import Model
+from django.http import HttpRequest
 from django.template import Context
 from django.urls import reverse
 
@@ -77,38 +78,6 @@ def url_with_perm_filter(value, arg1=None):
     """Resolve a URL and check if the current user has permission to access it.
 
     If permission check fails, the component that uses the value will be omitted from rendering.
-
-    Usage::
-
-        {% component "a" href="my_url_name"|url_with_perm:2 %}
-
-    The above example will resolve the URL "my_url_name" with the argument ``2``.
-
-    If you need multiple arguments you can use the ``with_arg`` filter::
-
-
-        {% component "a" href="my_url_name"|url_with_perm:2|with_arg:"another arg" %}
-
-    To pass kwargs you can use the ``with_kwargs`` filter::
-
-        {% component "a" href="my_url_name"|url_with_perm|with_kwargs:my_kwargs %}
-
-    Note that as there's no way to define a dictionary in the standard Django template language, you'll need to
-    pass it in context.
-
-    To do object level permission checks use the ``with_perm_obj`` filter to pass through the object::
-
-        {% component "a" href="my_url_name"|url_with_perm:obj.pk|with_obj:obj %}
-
-    Note that you still have to pass through the pk to resolve the URL with. Passing the object just allows the permission
-    checks to work without having to manually look up the object. Due to how the ``DetailView.get_object`` method works,
-    if you are not going to pass the object you must use ``with_kwargs`` to pass through the ID rather than a positional
-    argument::
-
-        {% component "a" href="my_url_name"|url_with_perm|with_kwargs:kwargs %}
-
-    Note that the above would do a query to retrieve the object, so it's better to pass the object if you have already
-    retrieved it.
     """
     pfv = NamedUrlDeferredProp(value, True)
     if arg1 is not None:
@@ -159,3 +128,29 @@ def unwrap_list(value):
             raise ValueError(f"Expected list of length 1, received length {len(value)}: {value}")
         return value[0]
     return value
+
+
+@register.filter
+def table_sort_order(request: HttpRequest, ordering_param: str = "ordering"):
+    """Extract the current sort ordering from the request GET parameters and return it as a list of dicts
+
+    Each ordering entry is a dict with keys "column" and "direction".
+
+    For example, the URL /foo?ordering=-bar,email would return::
+
+        [
+          {'column': 'email', 'direction': 'ascending'},
+          {'column': 'name', 'direction': 'descending'}
+        ]
+    """
+    query = request.GET.copy()
+    current_sorting_str = query.get(ordering_param)
+    if current_sorting_str:
+        return [
+            {
+                "column": x[1:] if x.startswith("-") else x,
+                "direction": "descending" if x.startswith("-") else "ascending",
+            }
+            for x in current_sorting_str.split(",")
+        ]
+    return []

packages/ap-frontend/alliance_platform/frontend/templatetags/bundler.py

@@ -147,82 +147,6 @@ def bundler_embed(parser: template.base.Parser, token: template.base.Token):
     By default, the tags are added to the HTML by the :meth:`~alliance_platform.frontend.templatetags.bundler.bundler_embed_collected_assets`.
     This allows assets to be embedded as needed in templates but all added in one place in the HTML (most likely the ``<head>``).
     You can force the tags to be outputted inline with ``inline=True``.
-
-    NOTE: This tag only accepts static values as :class:`extract_frontend_assets <alliance_platform.frontend.management.commands.extract_frontend_assets.Command>`
-    needs to be able to statically generate a list of paths that need to be built for production.
-
-    Args:
-        content_type: (optional) If set to either 'css' or 'js' only assets of the matching type will be embedded. If omitted
-            both types will be included (if available).
-        inline: If ``True`` the tags will be embedded inline, otherwise they will be added using the
-            :meth:`~alliance_platform.frontend.templatetags.bundler.bundler_embed_collected_assets` tag. Defaults to ``False``.
-        html_*: any parameter with a ``html_`` prefix will have the ``html_`` stripped and passed through to the embed tag
-            eg ``html_id="foo"`` would render ``<script id="foo" ...>`` for script tags
-
-    Usage with ``bundler_embed_collected_assets``:
-
-    .. code-block:: html
-
-        // in the base template (e.g. base.html)
-        <!doctype html>
-        {% load bundler %}
-        <html lang="en-AU">
-          <head>
-            {% bundler_embed_collected_assets %}
-          </head>
-          <body>{% block body %}{% endblock %}</body>
-        </html>
-
-        // in other individual templates, e.g. 'myview.html'
-
-        {% extends "base.html" %}
-        {% block body %}
-            {% bundler_embed "MyComponent.ts" %}
-            {% bundler_embed "logo.png" html_alt="My Component Logo" %}
-            <h1>My View</h1>
-        {% endblock %}
-
-    would output:
-
-    .. code-block:: html
-
-        <!doctype html>
-        <html lang="en-AU">
-          <head>
-            <script type="module" src="http://localhost:5173/assets/MyComponent.js"></script>
-            <link rel="stylesheet" href="http://localhost:5173/assets/MyComponent.css" />
-          </head>
-          <body>
-            <img src="http://localhost:5173/assets/logo.png" alt="My Component Logo" />
-            <h1>My View</h1>
-          </body>
-        </html>
-
-    Using ``inline=True`` instead:
-
-    .. code-block:: html
-
-        {% extends "base.html" %}
-        {% block body %}
-            {% bundler_embed "MyComponent.ts" inline=True %}
-            <h1>My View</h1>
-        {% endblock %}
-
-    would output:
-
-    .. code-block:: html
-
-        <!doctype html>
-        <html lang="en-AU">
-          <head></head>
-          <body>
-            <script type="module" src="http://localhost:5173/assets/MyComponent.js"></script>
-            <link rel="stylesheet" href="http://localhost:5173/assets/MyComponent.css" />
-            <h1>My View</h1>
-          </body>
-        </html>
-
-    Note that in the example above ``logo.png`` is always embedded inline as it is not a javascript or css file.
     """
     tag_name = token.split_contents()[0]
     args, kwargs, target_var = parse_tag_arguments(parser, token, supports_as=True)

packages/ap-frontend/alliance_platform/frontend/templatetags/react.py

@@ -95,138 +95,7 @@ def resolve_prop(value: Any, node: ComponentNode, context: Context) -> Component
 def component(parser: template.base.Parser, token: template.base.Token):
     """Render a React component with the specified props
 
-    There are three ways to specify which component to render. The first is for a `"common component" <https://react.dev/reference/react-dom/components/common>`_
-    which is to say a built-in browser component (e.g. ``div``)::
-
-        {% component "h2" %}Heading{% endcomponent %}
-
-    The other two are for using a component defined in an external file. These will be loaded via
-    the specified bundler class (currently :class:`~alliance_platform.frontend.bundler.vite.ViteBundler`). With
-    a single argument it specifies that the default export from the file is the component to use::
-
-        {% component "components/Button" %}Click Me{% endcomponent %}
-
-    With two arguments the first is the file path and the second is the named export from that file::
-
-        {% component "components/Table" "Column" %}Name{% endcomponent %}
-
-    The last option has a variation for using a property of the export. This is useful for components
-    where related components are added as properties, e.g. ``Table`` and ``Table.Column``::
-
-        {% component "components" "Table.Column" %}Name{% endcomponent %}
-
-    Note that this is only available when using named exports; default exports don't support it due to
-    ambiguity around whether the ``.`` indicates file extension or property access.
-
-    You can omit the file extension - the above could resolve to ``components/Table.tsx`` (``.js`` and ``.ts`` are also
-    supported). See :ref:`resolving_paths` for details on how the file path is resolved.
-
-    Props are specified as keyword arguments to the tag::
-
-        {% component "components/Button" variant="primary" %}Click Me{% endcomponent %}
-
-    Additionally, a dict of props can be passed under the ``props`` kwarg::
-
-        {% component "components/Button" variant="primary" props=button_props %}Click Me{% endcomponent %}
-
-    Children can be passed between the opening ``{% component %}`` and closing ``{% endcomponent %}``. Whitespace
-    is handled the same as in JSX:
-
-    * Whitespace at the beginning and ending of lines is removed
-    * Blank lines are removed
-    * New lines adjacent to other components are removed
-    * New lines in the middle of a string literal is replaced with a single space
-
-    So the following are all equivalent::
-
-        {% component "div" %}Hello World{% endcomponent %}
-
-        {% component %}
-            Hello world
-        {% endcomponent %}
-
-
-        {% component %}
-            Hello
-            world
-        {% endcomponent %}
-
-
-        {% component %}
-
-            Hello world
-        {% endcomponent %}
-
-    Components can be nested::
-
-        {% component "components/Button" type="primary" %}
-            {% components "icons" "Menu" %}{% endcomponent %}
-            Open Menu
-        {% end_component %}
-
-    You can use ``as <variable name>`` to store in a variable in context that can then be passed to another tag::
-
-        {% component "icons" "Menu" as icon %}{% end_component %}
-        {% component "components/Button" type="primary" icon=icon %}Open Menu{% end_component %}
-
-    All props must be JSON serializable. :class:`~alliance_platform.frontend.prop_handlers.ComponentProp` can be used to define
-    how to serialize data, with a matching implementation in ``propTransformers.tsx`` to de-serialize it.
-
-    For example :class:`~alliance_platform.frontend.prop_handlers.DateProp` handles serializing a python ``datetime`` and
-    un-serializing it as a native JS ``Date`` on the frontend. See :class:`~alliance_platform.frontend.prop_handlers.ComponentProp`
-    for documentation about adding your own complex props.
-
-    Components are rendered using the ``renderComponent`` function in ``ap_frontend_settings.REACT_RENDER_COMPONENT_FILE``. This can be modified as needed,
-    for example if a new provider is required.
-
-    .. note:: All props passed through are converted to camel case automatically (i.e. ``my_prop`` will become ``myProp``)
-
-    Server Side Rendering (SSR)
-    ---------------------------
-
-    Components will automatically be rendered on the server. See :ref:`ssr` for details about how this works.
-
-    To opt out of SSR pass ``ssr:disabled=True`` to the component after the component name::
-
-        {% component 'components/Button.tsx' ssr:disabled=True %}...{% endcomponent %}
-
-    Options
-    -------
-
-    Various options can be passed to the component tag. To differentiate from actual props to the component they are
-    prefixed with `ssr:` for server side rendering options, `component:` for general component options, or `container:`
-    for options relating to the container the component is rendered into.
-
-    - ``ssr:disabled=True`` - if specified, no server side rendering will occur for this component
-    - ``component:omit_if_empty=True`` - if specified, the component will not be rendered if it has no children. This is
-      useful for when components may not be rendered based on permission checks
-    - ``container:tag`` - the HTML tag to use for the container. Defaults to the custom element ``dj-component``.
-    - ``container:<any other prop>`` - any other props will be passed to the container element. For example, to add
-      an id to the container you can use ``container:id="my-id"``. Note that while you can pass a style string, it's
-      likely to be of little use with the default container style ``display: contents``. Most of the time you can just
-      do the styling on the component itself.
-
-    For example::
-
-        {% component 'core-ui' 'Button' ssr:disabled=True variant="Outlined"%}
-            ...
-        {% endcomponent %}
-
-    Limitations
-    -----------
-
-    Currently, attempting to render a django form widget that is itself a React component within another component will
-    not work. This is due to how django widgets have their own templates that are rendered in an isolated context. For
-    example, this will not work if ``form.field`` also uses the ``{% component %}`` tag:
-
-            {% component 'MyComponent' %}
-                {{ form.field }}
-            {% endcomponent %}
-
-    Alliance UI
-    -----------
-    Alliance Core UI components have pre-made tags for more convenient implementation.
-
+    See the templatetags.rst docs for more details.
     """
     return parse_component_tag(parser, token)
 

packages/ap-frontend/alliance_platform/frontend/util.py

@@ -16,9 +16,12 @@
 
 def get_node_ver(node_path: str) -> Version | None:
     """
-    Get the node verson from a given path
+    Get the node version from a given path
 
     if raise_errors is not True then exceptions will be swallowed and None will be returned on error
+
+    Args:
+        node_path: The path to the node executable
     """
     try:
         proc = subprocess.Popen(
@@ -36,6 +39,12 @@ def get_node_ver(node_path: str) -> Version | None:
 
 
 def guess_node_path(nvmrc_path: Path) -> str | None:
+    """Attempt to guess the node path based on the .nvmrc file
+
+    Args:
+        nvmrc_path: Path to the .nvmrc file
+    """
+
     # nvm's version strings aren't quite the same as those
     # used by python but the overlap makes it good enough