RFC: docs website layout demo

Tue Jan 13 01:09:59 UTC 2015

On 01/11/2015 05:13 PM, Jeff Fearn wrote:
> Hi Pete,
>
> On 12/20/2014 03:10 PM, Pete Travis wrote:
>> On 10/23/2014 04:21 PM, Jeff Fearn wrote:
>>
>> <TRIM!>
>>> So this thread has kind of died, I think it's because using bootstrap
>>> with the current HTML output is a monstrous job.
>>>
>>> I'd like to progress with getting the site updated to something
>>> similar to my demo then start a separate, longer, process to change
>>> the HTML publican generates so that it's much easier for people to
>>> radically change the
>>> styling.
>>>
>>> Thoughts?
>>>
>>> Cheers, Jeff.
>>>
>> Hey Jeff,
>>
>> Thanks again for spending some time on IRC recently.  I've spent a bit
>> more time on this, and have developed a few questions I hope you can answer.
>>
>> First, one of the things I've been struggling with was getting the style
>> applied to the homepage.  After trying a number of misguided things, I
>> actually looked at $sitehome/en-US/index.html and found this:
>>
>>     
>> $('#splash').load("https://admin.fedoraproject.org/docs-backend//en-US/splash.html
>> .article");
>>
>> The main copy on the page is loaded by this function, and of course it
>> strips the <head> out - so no CSS comes with.
> FYI we did this because loading the second header in to the page had
> some very weird effects on some browsers.

That's logical, two <head>s doesn't make sense.  The result, though, is
that the styles that would apply to the main content section aren't ever
loaded, and we loose some consistency between the home page and the
books.  Is that something to just accept, or can you offer some
suggestion or enhancement?

>> What we *do* get is:
>>
>> - chrome.css
>> - site_overrides.css
>> - splash.css
>>
>> With your help, site_overrides.css is coming from the docsite-publican
>> (home) package now.  The other two files I had to manually copy in from
>> /usr/share/publican, and if I recall correctly, I ended up copying over
>> all of /usr/share/publican/sitetemplate/ . - Is there an RPM method for
>> doing this?
> sitetemplate gets copied over whenever you run "publican update_site".
I see.  Would it make sense to call `publican update_site` in %post of
brand or splash packages? I can't see that it would hurt anything, and
would get closer to a package-only deployment.
>
>> The CSS files that aren't coming along are:
>>
>> - db4.css
>> - brand.css
>> - print.css
>>
>> This doesn't seem right.  The home page should have the branding,
>> right? 
>>  Is a custom site template needed here?
> No, db4.css & print.css also get put in place by running update_site.
>
> brand.css was removed and should not be being required.
>
> Are you using publican from the devel git branch? I did do some changes
> to get the shiny happening, but I'm fresh back from holidays and can't
> recall everything I did specifically for this :}
>
> Cheers, Jeff.
>

hmm.. I'll have to investigate our usage of brand.css. Without it,
brand-specific style would only come from site_overrides.css and not the
brand; with the latter not being provided by the brand, it seems like
taking it out means maintaining the same styles in both files.

Publican installed here is publican-4.1.3-0.el6.noarch.  I suppose I, or
someone anyway, should take responsibility for updating the el6-docs
tag's publican and dependencies... but, I'm not a fan of putting our
production site on publican git.

-- 
-- Pete Travis
 - Fedora Docs Project Leader
 - 'randomuser' on freenode
 - immanetize at fedoraproject.org