Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add an introduction to HTML templating #13430

Open
wants to merge 7 commits into
base: master
Choose a base branch
from

Conversation

vwheeler63
Copy link
Contributor

Purpose

To more quickly orient the reader who is new to HTML templating. (I was recently a beginner on the topic, and I found the introductory section I added to be missing, which made it more difficult to understand the subsequent content.)

References

@AA-Turner AA-Turner changed the title docs(templating.rst): add orientation for those new to HTML templating Add an introduction to HTML templating Mar 13, 2025
@vwheeler63
Copy link
Contributor Author

vwheeler63 commented Mar 14, 2025

Honored to be in contact with you, Mr. Turner! 😄 ( @AA-Turner ) I love your edit! It's exactly what I needed the other day when I started learning about Templates!

altering Sphinx's source code, meaning that the Sphinx core can provide basic HTML
generation, independent of the final output.

Since template files function similar to Cascading Style Sheets, generating HTML
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vwheeler63 can you elaborate on this line please? I'm not sure I follow on the similarity between CSS and templates.

Copy link
Contributor Author

@vwheeler63 vwheeler63 Mar 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vwheeler63 can you elaborate on this line please? I'm not sure I follow on the similarity between CSS and templates.

What I meant to convey there is about the relationship between templates, where "more local" templates can inherit from higher templates and override as much of them as desired, from a tiny bit (e.g. one block), up through the whole thing. And in that respect, I find that similar (at least in my mind) to CSS. If that's not actually a good comparison, then perhaps it would be better simply to state explicitly that the more local template can override as little or as much of the higher-level template as desired? (Note: while I am a 32-veteran developer, I'm new to web development (and learning), so my view of CSS is probably limited compared to yours.) Perhaps it shares a deeper similarity to inheritance in O-O languages.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vwheeler63 can you elaborate on this line please? I'm not sure I follow on the similarity between CSS and templates.

I will try an alternate description simply using inheritance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants