RFC: docs website layout demo

Fri Oct 24 06:17:31 UTC 2014

On 10/13/2014 03:22 PM, Jeffrey Fearn wrote:
> Hi Pete,
TRIM!
> 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.

 Hi again,

Thanks for bring this thread up again.  Sorry for such an open-ended
question, but can you list out the RPMs we should have, and what RPMs
the mentioned files should belong to? The changes to the CSS layout
you're describing sound friendly, but I was confused to begin with :P

Like, the splash - is that docsite-publican for us?  The
site-overrides.css - that doesn't go in the publican-fedora brand with
all the other css?  Where do the product splash pages come from? How do
I build a product version level splash? What should be providing
chrome.css? Since some of these files aren't in existing RPMs, I'm not
sure where to put them, and it seems like the SPECs are hardcoded by
publican. 

I contrived a site[1] where the splash? pages seemed to install to
something like /var/www/html/ - but all the docs installed to something
like /var/www/html/docs/, and the latter directory had resources that
the html in the former wanted.  I'm sure I went wrong somewhere along
the way, or just have a tragic misconception about the way it works. 
Trying to wrap my mind around what packages installed what files and
where is how I wandered off into poking at spec file templates;  I don't
*know* that I want spec template changes, I just know I haven't been
able to produce RPMs that provide the expected result.  I moved some
things in manually, but it still doesn't quite turn out as I expect.

With file ownership out of the way, is there an ordering concern? ie
change the brand, package the brand, change the site splash, build the
site splash with the new brand, then install those packages before
adding docs, then install the product splashes?

Thanks again for your patience, and persistence.

[1] docs-backend-01.phx2.fedoraproject.org
     viewable via https://admin.fedoraproject.org/docs-backend/
    @sysadmin-docs (notably rudi) have ssh access if you want more info
directly from the box

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: OpenPGP digital signature
URL: <http://lists.fedoraproject.org/pipermail/docs/attachments/20141024/4a248d0a/attachment.sig>