| From: | "Jonathan S(dot) Katz" <jkatz(at)postgresql(dot)org> |
|---|---|
| To: | Peter Geoghegan <pg(at)bowt(dot)ie> |
| Cc: | Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us>, Pg Docs <pgsql-docs(at)lists(dot)postgresql(dot)org> |
| Subject: | Re: Duplicating website's formatting in local doc builds |
| Date: | 2020-02-12 03:56:27 |
| Message-ID: | 86f03290-e60c-855e-786a-d1b75c254811@postgresql.org |
| Views: | Raw Message | Whole Thread | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-docs |
On 2/11/20 3:49 PM, Jonathan S. Katz wrote:
> On 2/11/20 3:41 PM, Peter Geoghegan wrote:
>> On Tue, Feb 11, 2020 at 11:40 AM Jonathan S. Katz <jkatz(at)postgresql(dot)org> wrote:
>>> Anyway, attached is a first attempt at a patch. I tried a few different
>>> variations but in my quick review of it, I could not figure out how to
>>> make a XSLT respect having multiple stylesheets (likely due to my lack
>>> of familiarity with XSLT).
>>
>> I tried this patch out.
>
> Thanks!
>
>> The alignment is a little off, since the docs
>> don't appear in the website's frame, and lack the website's header. It
>> would be nice if the same margins appeared to the left and to the
>> right.
>
> Yup, that's a direct result of not having the Bootstrap base.
>
>> But even still, it's a vast improvement.
>
> Cool.
I played around with this for a bit longer, became a bit more familiar
with DocBook[1] (and a lot of other pages, but this one seemed
relevant), and here is what I came up with:
As I mentioned, the way pgweb works is that it wraps a root element (the
<div id="docContent">...</div>) around the imported HTMl from the
generation, which allows it to apply the various website styles. This is
important, because it allows us to apply some general style rules, but
namespace them specifically to the documentation. Hold this thought for
a moment.
When calling "make STYLE=website html", this turns on a flag that embeds
the URL to the old "docs.css" content that we generated. I did an
experiment where I overloaded the "dynamic CSS generator" we have in our
code to include the bootstrap.css files (as well as some others) in
addition to our new base CSS. This demonstrated a marked improvement in
the output from the above command, but it was still not perfect: the CSS
rules still expect there to be the #docContent namespace.
I thought this would be a good area to explore to see if I could get the
#docContent ID wrapped around the content body. As I was writing this
note (where actually I was about to throw in the towel), on a hunch I
improved my Googling and found a solution (attached).
This works with pgweb as pgweb extracts the content from the <body> tag
that is generated by "make html" so this is unaffected.
For this solution to fully work, I also need to make a patch to pgweb. I
have it 80% done, where the final 20% is getting rid of some annoying
errors of files it is looking for (the Bootstrap minification expects a
CSS map file. I believe I can silence that).
It's not perfect: we don't have a full container around the generated
documentation so you can't see it exactly in terms of how it's render on
the website, but it's way closer to the look and feel. I might be able
to add a few more attributes to make it look closer to the website in
that regard, though after there is consensus that this approach is ok.
That said, I think this is a happy compromise that allows said mode to
appear mostly like what you would find on the website.
Thanks,
Jonathan
[1] http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html
| Attachment | Content-Type | Size |
|---|---|---|
| website-formatted-docs-v2.patch | text/plain | 1.1 KB |
| From | Date | Subject | |
|---|---|---|---|
| Next Message | Alexander Lakhin | 2020-02-12 04:05:06 | Re: Getting our tables to render better in PDF output |
| Previous Message | Justin | 2020-02-11 23:04:02 | Re: How to restore roles without changing postgres password |