readthedocs / readthedocs/ext-theme
Templates: normalize template naming
Nobody has claimed this yet.
- 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.htmland{application}/{model}_detail.html, etc are preferred - Additional nested paths are helpful for some applications, such as
templates/projects/edit/webhook_list.htmlfor project setting views - In cases like organizations and projects, templates related to the project and organization UI are grouped under
templates/projectsandtemplates/organizationsinstead of applications likebuildandsubscriptions. It's confusing to have some project admin UI templates outside theprojectsapplication. 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 mainprojects/notification_list.htmlincludes the partialprojects/partials/notification_list.htmlso 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.htmland 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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