RFC: docs website layout demo

[Jeffrey Fearn]

Hi Pete,

----- Original Message -----
> On 10/13/2014 12:34 AM, Jeff Fearn wrote:
> > On 10/10/2014 08:30 PM, Jeffrey Fearn wrote:
> > > Hi, Rudi asked me to do a demo of how Fedora could make a rebuilt
> > docs website look, so I've made a demo site & tweaked it a bit. Before
> > I spend too much effort on it I thought I'd open it up for input.
> >
> > > I wanted to get a bit more done before the weekend, but time slipped
> > away. I wanted to get it out for some feedback over the weekend so I
> > can do some more on Monday, so I'd thought I'd just put it out there
> > and hope
> > > people can understand it is only half baked.
> >
> > > Some of the stuff I did for this I liked so I've started migrating
> > the template changes back in to publican, leaving this site with just
> > some colour changes on what a default web_style 2 site will look like.
> > I'll
> > > update my fedora people site next week so show what a default site
> > will look like.
> >
> > > I've made a script to pull out most of the docs packages from git,
> > and run through a bunch of branches per book, and try to build them
> > with the latest publican. I'll make the script available next week for
> > people who
> > > want to build their own copy. It should be useful to QA the process
> > as it spits out a log file out for each repo and branch so you can get
> > a good list of what's broken and what's not. I'll also put those up on my
> > > fedora people site next week ... If I have any quota left :D
> >
> > I've pushed this on to the demo site [1], comments at the top hold the
> > instructions.
> >
> > It needs tweaks to docsite-publican, hope to get those committed soon.
> >
> > It also needs Fedora_Splash which contains the blurb on the Fedora
> > products page and the groupings, not sure what to do about that.
> >
> > It will still work without those things, it just won't look exactly
> > the same.
> >
> > > Demo site is https://jfearn.fedorapeople.org/fdocs/en-US/index.html
> >
> > > I think this is a pretty good layout
> > https://jfearn.fedorapeople.org/fdocs/en-US/index.html#Fedora
> >
> > > Colours are hard :-/
> >
> > > Note if you click a group, below the versions, then it filters out
> > all the other groups.
> >
> > > Note that in the "System administration" group for Fedora 20 there
> > is an external link "The Ways And Means Of Pants" which is a fake URL,
> > if you have a couple of examples of real external links you'd like in that
> > > group, or any other group, I'd be happy to swap out the fake one.
> >
> > > I haven't changed the brand XSL for the html payload, I'd like to
> > remove the old left and right logos at the top of the pages. They
> > aren't really needed given the menu content.
> >
> > > e.g.
> > https://jfearn.fedorapeople.org/fdocs/en-US/Fedora/20/html/Installation_Guide/index.html
> >
> > > bah I just noticed a bug on that page,  the first two items in the
> > navigation menu are swapped ... :(
> >
> > > I'm sure there are lots more :}
> >
> > > I've built html, html-single, epub & pdf.
> >
> > > The site is only in en-US, it's 417M and I'm not sure the hosting
> > people would be happy if I hosted more languages :)
> >
> > > Anyway, it's Friday evening and the wine is calling, please reply if
> > you have any ideas or feedback, beware that I'm currently hacking on
> > the publican devel branch, so I might steal any really cool ideas for
> > > publican.next ;)
> >
> > > Cheers, Jeff.
> >
> > > P.S. All the RSS feeds on there should work, but you probably do not
> > want to sign up for that site!
> >
> >
> > Cheers, Jeff.
> >
> > 1: https://jfearn.fedorapeople.org/fdocs/rebuild_site.sh
> >
> 
> Hey Jeff,
> 
> I'm exited to see your interest in our Publican site.  We've been trying
> to build a system with publican-created src.rpms built by koji, and
> installed to a virtual machine.  The infrastructure part has gone fairly
> well; any package we push out is automatically installed and the site
> updated.
>
> The part of the process I've really struggled with is the interaction
> between the branding, the table of contents stuff, the landing page, the
> splash (which I wasn't aware of as a discrete document type,) the CSS
> applied to the toc/landing page/splash, the spec file templates used for
> landing pages or docs or sites or splashes, the publican.cfg for the
> landing page or the site settings... well, I'll just say every time I
> try to work on it, I get lost.  I realize that's a very non-specific
> problem description, but after hours of working with the existing site,
> with CSS that people on our team worked out, or just starting a publican
> site from scratch following your user guide, I don't feel like I'm at
> the point of even intelligently asking for help.

Yeah you'd think a tool like publican which is used almost exclusively by writers would have better docs, but getting writers to help document the stuff has always been extremely painful and unsuccessful. :(

The section in the PUG is [1] if there are specific things that are missing or confusing bugs are appreciated.

There have been some bugs too, like fairly recently (in publican terms) I removed the brand CSS from the splash pages and did a lot of separation of the CSS content because it was just a nightmare to maintain.

I'll try and describe how it works on my demo site as it up to date and should have the least complex interactions.

The site is basically split in to two areas, the splash pages and the books.

Both areas use chrome.css to style the menu.

The splash area uses splash.css to style body content.

The book area uses db4.css or db5.css to style body content. I split them because having one CSS file for docbook4 and docbook5 was unmaintainable.

The book area uses brand.css to override the style of body content. You need one brand for db4 and one for db5, so you don't need to try and style both in the one brand.css file.

Both areas use site-overides.css to override the styles.

Note that the CSS still has some overlap but I am gradually moving the styles in to the right CSS files.

There are 3 levels of splash pages, site (or welcome page), product and version. These are normal publican books that are processed slightly differently.

The site level splash page contains:
1: site-overides.css
2: the front page blurb
3: Ads for the splash pages (if you want them)

The product level splash page contains:
1: the product page blurb
2: Groups for books
3: External links

The version level splash page contains:
1: the product version page blurb

Templates are another story, you should not have to modify the spec file template, if you have specific requirements we can either get it added as a brand config option or I can show you how to override the templates entirely in your brand.

The splash pages are also generated using templates, and again with specific requirements we can look to parameterise them or override them entirely.

> rkratky and yruseva worked up CSS for a web_style=2 site that I rather
> like, at
> https://rkratky.fedorapeople.org/docsweb/mockup/en-US/index.html .

Yeah my stuff is web_style 2 as well since AFAIK no one is using web_style 1 and it's not QA'd ATM.

lol I wish I'd know about this before, it's very similar really :P

>  I
> really like elements from your demo too, like the secondary categories
> and the format selection icons (although replicating the Adobe logo for
> PDFs probably should go :P )

Those glyphs are from font awesome, it's GPL compatible and should be fine.

>.  The social media things at the bottom are
> intriguing; our marketing team would probably like to explore the
> potential there.

Yeah I never understood why no one ever uses footer in teh site.cfg file ... although any text on the links would not be translatable :(

> Ideally, I'd like to have all of the components and docs we need tagged
> into the el6-docs repo, and the site would rebuild by simply installing
> all the Publican document packages available on a clean virtual
> machine.  Can you help us put all these pieces together into a
> replicatable site, or at least talk me through some stumbling blocks
> sometime?

Yeah I'm happy to help get this up and running for you all, publishing should be an easy last step not a high jump.

Cheers, Jeff.