Add templates for generated pages

[melissawm]

Highest priority is to set up templating for the tags overview page.

[nebelgrau77]

How would that work? I still know very little about Sphinx, so I'm not sure how you intend this.

[melissawm]

I was thinking to use some sort of templating to configure the look and feel of the tags overview page. For example: https://stackoverflow.com/questions/13209597/override-html-page-template-for-a-specific-sphinx-document

I tried looking for solutions but I don't have any specific ideas right now.

[nebelgrau77]

Yeah, I get the template idea, I have some minor modifications like that in my project (some are pretty difficult to implement, e.g. if you want your logo in the sidebar to be below the title - no problem! but to have it above it I ended up making a single logo+title png file :D) But would you like to add some templates for the users to choose from, or somehow have the extension to generate them?

[JWCook]

I would find this useful as well.

Style

templating to configure the look and feel of the tags overview page

For customizing style, that can already be done on the user's end with Sphinx's html_css_files option.

Content

Instead of making HTML templates, this could be done with 4 small markup templates:

• Tags overview (rST)
• Tag page (rST)
• Tags overview (MyST)
• Tag page (MyST)

This would basically replace what sphinx-tags currently does in Tag.create_file() and Entry.tagpage().

Extension example

Here's an example for the autosummary extension, with both the directive code and template files: https://github.com/sphinx-doc/sphinx/tree/master/sphinx/ext/autosummary

• The part that renders the templates is in AutosummaryRenderer.
• The context passed to those templates is built in generate_autosummary_content().
• Users can override the module template, for example, by putting their own version under <root>/_templates/module.rst_t and setting templates_path in conf.py:

  templates_path = ['_templates']

Jinja example

Here's a quick (probably incorrect, but close enough) example of what a MyST template for tagsoverview.md might look like:

(tagoverview)=
# {{ tags_overview_title }}

{% raw %}
```{toctree}
{% endraw %}
---
caption: {{ tags_index_head }}
maxdepth: 1
---
{% for tag in tags %}
  {{ tag.name }} ({{ len(tag.items) }}) <{{ tag.name }}>
{%- endfor %}