| 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 13:15:08 |
| Message-ID: | 716a39ec-6f56-0280-8d4b-b246176c6a3d@postgresql.org |
| Views: | Raw Message | Whole Thread | Download mbox | Resend email |
| Thread: | |
| Lists: | pgsql-docs |
On 2/11/20 10:56 PM, Jonathan S. Katz wrote:
> 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.
Realizing this might be a bit wonky to test, I made the necessary
changes to pgweb and pushed those, so the results of the patch now look
like what I was seeing. If you were previously testing it, rebuild the
docs with STYLE=website and it should now look better.
Thanks,
Jonathan
| From | Date | Subject | |
|---|---|---|---|
| Next Message | Adrian Klaver | 2020-02-12 16:39:27 | Re: How to restore roles without changing postgres password |
| Previous Message | Andrus | 2020-02-12 10:06:56 | Re: How to restore roles without changing postgres password |