Re: Duplicating website's formatting in local doc builds - Mailing list pgsql-docs
| From | Jonathan S. Katz |
|---|---|
| Subject | Re: Duplicating website's formatting in local doc builds |
| Date | |
| Msg-id | 716a39ec-6f56-0280-8d4b-b246176c6a3d@postgresql.org Whole thread Raw |
| In response to | Re: Duplicating website's formatting in local doc builds ("Jonathan S. Katz" <jkatz@postgresql.org>) |
| Responses |
Re: Duplicating website's formatting in local doc builds
("Jonathan S. Katz" <jkatz@postgresql.org>)
|
| List | 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@postgresql.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
Attachment
pgsql-docs by date: