HTML templates #299
HTML templates #299
Conversation
It load the templates HTML with XMLString. Not sure it's the best practice... I've also reworded _writeDocsForOne() method so we can understand what's going on Wrote a draft header file for twisted to try out
Error mesage if the custom template writer class do not support --template-dir
Codecov Report
@@ Coverage Diff @@
## master #299 +/- ##
==========================================
- Coverage 87.09% 86.98% -0.11%
==========================================
Files 22 22
Lines 4076 4242 +166
Branches 821 843 +22
==========================================
+ Hits 3550 3690 +140
- Misses 340 360 +20
- Partials 186 192 +6
Continue to review full report at Codecov.
|
|
These are just some first impressions, I'll do a more thorough review later. Thanks for picking this up. I haven't thought about customization in detail yet, but this is certainly a big improvement over monkeypatching. We should define and document a backwards compatibility strategy. Even if we can't actually solve that problem, having a way to warn "your templates were written for pydoctor oldversion; these things need updating:" would be much better than crashing or silently producing wrong output when using outdated templates. I think it's best if we merge this after the next release, both because of timing and because of compatibility. I have several ideas on presentation that I want to try out after releasing and some of those might break templates; releasing template customization and then breaking most templates in the release after will not make users happy.
Over the years I've become convinced that singleton is an anti-pattern. It often starts out simple, but it will cause problems later which by then are hard to solve. I should probably do a blog post on it some day. Is it possible to do this without a singleton, via
This is very useful in evaluating the changes. But by the time we're ready to merge, the Twisted templates should be moved to Twisted's repo. In a quick look over the code, I saw some parts use In situations where we're dealing with paths coming from the source being analyzed and we want to be careful, |
alongside the main title.
I agree
Should we store the pydoctor version in every template i.e.
Probably! But I think this involves using another way than the static method |
Twisted templates XMLString warns if we pass something other than a FilePath, and it's also the interface used in pydoctor |
|
Maybe the "generated by" message should be in |
|
There two things here:
I think the meta generator tags should appear in all templates (except the place holders). Edit: The twisted templates can have missing tags We don't need to handle them, just print a warning saying the users should check the newer templates and update theirs if they want to. |
The module index is only one of the pages this method writes.
By doing the slot filling in code, we ensure it will happen always, regardless of template customizations that are done.
This removes some inconsistencies between pages, where some were using slots and others were using renderers (with two different names for the pydoctor version, too).
|
Hey @mthuurne , do you still want to add more commits to this PR ? |
There was a problem hiding this comment.
Hey @mthuurne , do you still want to add more commits to this PR ?
Yes, I want to remove as many differences between the different types of pages as possible. I already did a bit for the slots, but there are more slots and renderers that we could make available on all pages. Also using the same footer on every page would be nice (as we discussed in chat).
I have some time available today and tomorrow, so expect new commits soon.
Since node IDs have to be unique within a document, this renderer could be used only once on each page. The color set for `#projecthome` was the same as the hover color that Bootstrap would otherwise set, so removing it doesn't change anything in the presentation.
There used to be a renderer for a possibly hyperlinked name and a slot that would insert the name without a link. Now we use a slot at the page level, to make it available everywhere. In practice, this means the project name in the footer is now a link.
This was already unused by our templates, but kept around to not break Twisted. However, Twisted's templates will have to be redesigned anyway when the template rework lands, so now is a good time to remove this. A comment states that the CSS needs to be removed as well, but I can't find any CSS relevant to this, so I guess it was already removed as part of earlier cleanups.
|
Hey, I saw that you removed the special id for the project home button. The fact is that it was not useless. It's effectively not the same color as the bootstrap default: it was slightly blue and would indicate the users that the link would exit the current site. But that's not a big deal. Also for the footer I'll add some minor CSS changes, you'll tell me what you think |
You are correct. It seems I checked the hover color that Bootstrap assigns to the other links in the header, which is equal to the hover color the project link had. But since the project link is inside a Shall I override the link hover color for
I'll have a look (nothing seems to have been pushed yet). |
|
I've done a few minor edits. For the link color, I've used a css class, which solves the issue while keeping a different hover color for the project home link in the navbar. I hope that the PR can now be merged! |
Co-authored-by: Maarten ter Huurne <maarten@treewalker.org>
The `templatefilepath()` function was only called by pydoctor itself, so it can be safely removed now. The `templatefile()` function is not called by Twisted, but is monkeypatched by Twisted. It does need to exist since Twisted will save the original function and restore it after it's done. I updated the docstring to make it clear that Twisted does not call it.
|
There are probably still things that can be improved, but it's already a lot better than the old template code and other development work cannot easily use the new template system until it's merged. So I merged it now. Thanks for your hard work and your patience. |
Hello,
This PR tries to solve #3, it introduces a new argument:
--template-dir.The users can overwrite any template files contained in the
pydoctor/templates.Custom place holders have been created:
header.html,subheader.htmland a CSS sheet:extra.css. Overwriting those won't create any warnings on upgrades since they are empty by default. Actual template files have a version number ( independent from pydoctor's ). Overwriting those is supported but might trigger warnings for missing information if the default template version has increase. (So Updating pydoctor doesn't mean all your custom templates will be outdated)This feature will break (but not crash) the Twisted custom build. Twisted should use the template system to insert custom HTML and JS into the pages.
New errors or warnings:
With the current implementation it's hard to distinguish a placeholder template (that is not supposed to have a version) and a normal HTML template with invalid version tag...
Structural changes:
Pageto avoid duplicating the rendering of :Nav, header.html, footer.html and pageHeader.html.TemplateElementthat is created by passing a ITemplateLoader to the constructor.TemplateLookupobject is core of the templates handling system logic.Templateobject represent any file inpydoctor/templatesor custom templates files. They are identified by their filenames.The Template object is abstract class.
Template.fromfile is the factory to the concrete templates. For now concrete templates are _HtmlTemplate or _StaticTemplate.
IWriterthat define the 3 methods.Style changes:
navlinks: List of links to add in the nav header.