readthedocs / readthedocs/ext-theme

Templates: normalize template naming

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

Nobody has claimed this yet.

Accepted Improvement
Dominant language
HTML
Stars
12
Forks
6
Avg merge
13h 25m
Merged PRs (30d)
1

Description

You'll find in the templates path that a lot of templates are replaced with symlinks to alternate paths. This is a temporary change to avoid making application changes to fix historical accumulation of varying patterns for template paths.

Eventually, we should come back and make application changes to normalize all of the template names, so we're not using competing standards across applications.

The standards used here aim to keep templates grouped by function and where in the application the templates are used. Some loose rules that template names are aiming for:

  • Template symlinks are added for templates that aren't using standard Django template names. The standard form of {application}/{model}_list.html and {application}/{model}_detail.html, etc are preferred
  • Additional nested paths are helpful for some applications, such as templates/projects/edit/webhook_list.html for project setting views
  • In cases like organizations and projects, templates related to the project and organization UI are grouped under templates/projects and templates/organizations instead of applications like build and subscriptions. It's confusing to have some project admin UI templates outside the projects application. In some cases these are just symlinked to avoid moving anything.
  • /includes/... is reserved for elements that can appear anywhere in the UI. These are not for application specific templates.
  • {application}/partials/... are for portions of UI that are broken out into their own files for easier maintenance. For example, the main projects/notification_list.html includes the partial projects/partials/notification_list.html so that we can utilize the common table listing template.
Notable issues
  • We drop a lot of templates in projects/ with redundant names like {application}/{application}_{model}_detail.html (projects/project_notifications_list.html)
  • We've used some non standard suffixes on templates, we should instead just use list/detail/form.
  • We've combined some views to be list/edit views, and have some listing views named ..._edit.html and other flavors of this.
Work
  • Go through the template directory, find template symlinks, and update the necessary application view code so we can remove the symlink.
  • Update some of the existing template names if necessary

Contributor guide

No contributing guide indexed for this repository

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 in the templates path by inventorying the template symlinks and the naming patterns described in the issue. Trace each symlink to the application view code that uses it, then determine the necessary template renames and reference updates; done means the naming is consistent and the unnecessary symlinks can be removed.

Written by the indexing model from the issue text.

Assessment

Tech stack
django, html
Domain
frontend
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.