Add an introduction to HTML templating #13430
Conversation
AA-Turner
changed the title
Co-authored by @AA-Turner Co-authored-by: Adam Turner <[email protected]>
|
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! |
...separate concepts into separate paragraphs.
| 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 |
There was a problem hiding this comment.
@vwheeler63 can you elaborate on this line please? I'm not sure I follow on the similarity between CSS and templates.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
@AA-Turner It's also possible that detail about the inheritance is not needed in an orientation paragraph. As a student, however, I found it helpful to quickly get my mind around the nature of template files and the amazingly powerful tool that they are, and why they were/are a genius design choice for Sphinx to use to push HTML through to get a final result! 😄
|
Thanks @vwheeler63, a very useful addition. A |
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