Re: Duplicating website's formatting in local doc builds
| От | Jonathan S. Katz |
|---|---|
| Тема | Re: Duplicating website's formatting in local doc builds |
| Дата | |
| Msg-id | 86f03290-e60c-855e-786a-d1b75c254811@postgresql.org обсуждение исходный текст |
| Ответ на | Re: Duplicating website's formatting in local doc builds ("Jonathan S. Katz" <jkatz@postgresql.org>) |
| Ответы |
Re: Duplicating website's formatting in local doc builds
|
| Список | 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@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. Thanks, Jonathan [1] http://docbook.sourceforge.net/release/xsl/current/doc/html/index.html
Вложения
В списке pgsql-docs по дате отправления: