openedx / openedx/edx-django-utils

Update docs for custom attributes to add annotations

Open
#328 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted
Dominant language
Python
Stars
28
Forks
31
Avg merge
7d 6h
Merged PRs (30d)
1

Description

Use of custom attributes is documented here:
https://edx.readthedocs.io/projects/edx-django-utils/en/latest/monitoring/how_tos/using_custom_attributes.html

We've been annotating custom attributes as seen in these examples:
https://github.com/search?q=(org%3Aedx%20OR%20org%3Aopenedx)%20custom_attribute_name&type=codev

    # .. custom_attribute_name: jwt_auth_check_symmetric_key
    # .. custom_attribute_description: True if symmetric keys will also be used for checking
    #   the JWT signature, and False if only asymmetric keys will be used.
    set_custom_attribute('jwt_auth_check_symmetric_key', decode_symmetric_token)
  1. The docs should detail this so we can more easily point people to this.
  2. As part of this or a separate issue, we should add Sphinx documentation for these annotations like was done for toggles and settings in https://github.com/openedx/code-annotations/tree/master/code_annotations/contrib/sphinx/extensions

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the linked using_custom_attributes.html page and compare the annotation examples in the issue. Then inspect the code_annotations/contrib/sphinx/extensions reference to assess the requested Sphinx support. Done means the custom-attribute annotations are documented and the Sphinx work is either implemented or clearly separated into its own issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
django, python
Domain
documentation, tooling
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.