Add comprehensive documentation for URL namespacing #13863
Conversation
Build Artifacts
|
rtibbles
left a comment
rtibbles
left a comment
There was a problem hiding this comment.
I can't request changes on my own PR, but this needs some tweaks before this is ready to merge.
rtibbles
force-pushed
the
claude/document-url-namespacing-011CUQYEpBAnT92bezhd5Mr1
branch
from
770c2a1 to
44c4698
Compare
rtibbles
force-pushed
the
claude/document-url-namespacing-011CUQYEpBAnT92bezhd5Mr1
branch
from
44c4698 to
4c864ef
Compare
|
This is potentially still a little verbose for my taste - but I'd rather have input from others about whether these are useful additional examples and documentation or just unnecessary verbiage. |
marcellamaki
left a comment
marcellamaki
left a comment
There was a problem hiding this comment.
one v small nitpick. other than this it looks fine. future marcella may have a opinion about this once she actually has to USE this documentation to build something and finds it confusing in a non-predictable way, but for now it seems like a solid overview and worth merging even if we continue to iterate.
|
|
||
| ```python | ||
| # ✅ GOOD | ||
| router.register(r"facility-user", FacilityUserViewSet, basename="facilityuser") |
There was a problem hiding this comment.
despite this being the "good" example, it does not actually use underscores? or is it that the basename doesn't have a - ?
There was a problem hiding this comment.
It's that the basename doesn't have a -, the url path can!
There was a problem hiding this comment.
I am okay with the url path having a -. My issue is that this is supposed to be an example of the good use of underscores, and there are none to be found
There was a problem hiding this comment.
Updated, and also added a note about cross-plugin URL references.
This commit adds extensive documentation for the URL namespacing system used throughout the Kolibri codebase, addressing issue #9435. Changes include: - New comprehensive how-to guide: "Working with URLs and API Endpoints" that covers: * URL naming conventions (kolibri:namespace:resource_endpoint) * How to define URLs in Django backend (ViewSets, routers, custom URLs) * How to use URLs in JavaScript frontend (direct access, API Resources) * Complete explanation of the backend-to-frontend URL pipeline * Best practices and debugging tips * Advanced topics (custom endpoints, direct endpoint access) - Updated existing API endpoints documentation with URL namespacing overview and cross-reference to the new guide - Updated frontend core architecture documentation to explain URL namespacing with practical examples - Added the new guide to the howtos index The documentation explains how URL namespacing works implicitly in the API resource layer and explicitly in frontend code (e.g., urls['kolibri:core:driveinfo-list']), providing developers with a complete understanding of the system. Fixes #9435 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
rtibbles
force-pushed
the
claude/document-url-namespacing-011CUQYEpBAnT92bezhd5Mr1
branch
from
4c864ef to
1d2ed9e
Compare
Summary
New how-to guide: "Working with URLs and API Endpoints" that covers:
Updated existing API endpoints documentation with URL namespacing overview and cross-reference to the new guide
Updated frontend core architecture documentation to explain URL namespacing with practical examples
Added the new guide to the howtos index
The documentation explains how URL namespacing works implicitly in the API resource layer and explicitly in frontend code (e.g., urls['kolibri:core:driveinfo-list']), providing developers with a complete understanding of the system.
References
Fixes #9435
Reviewer guidance
❗ 🤖 Generated with Claude Code ❗
Are there any parts that are too verbose, and just add fluff rather than useful variation? Are there any explicitly duplicative parts? Any inaccuracies?