Обсуждение: Documentation
Documentation for pgAdmin is really weak right now. Just to take an example, I don't know where a plugin file is described. The real question is how we do this. Right now, the documentation is a set of HTML files. Which is fine for some people and not for others. Kind of hard to get a consistent style. Kind of hard to get a good PDF and CHM file out of it. Not sure we really need these formats, I'm sure we want a consistent style. The only way to get all these options, AFAICT, is to use Docbook. SGML or XML. I have no problem working with Docbook, but I'm not sure everyone feels the same. I really prefer XML because of the toolset we can use (which seems, at least to me, in much better shape than the SGML one). Anyone has better ideas? -- Guillaume http://www.postgresql.fr http://dalibo.com
On Fri, Sep 24, 2010 at 10:29, Guillaume Lelarge <guillaume@lelarge.info> wrote: > Documentation for pgAdmin is really weak right now. Just to take an > example, I don't know where a plugin file is described. > > The real question is how we do this. Right now, the documentation is a > set of HTML files. Which is fine for some people and not for others. > Kind of hard to get a consistent style. Kind of hard to get a good PDF > and CHM file out of it. Not sure we really need these formats, I'm sure > we want a consistent style. > > The only way to get all these options, AFAICT, is to use Docbook. SGML > or XML. I have no problem working with Docbook, but I'm not sure > everyone feels the same. I really prefer XML because of the toolset we > can use (which seems, at least to me, in much better shape than the SGML > one). > > Anyone has better ideas? I've chatted with Dave about this a couple of times lately. at the time I suggested using RST and sphinx (http://sphinx.pocoo.org/). I think this is a much nicer thing to work with than docbook. It might not scale to as complex documentation (I'm not sure I'd like to see the pg docs redone in it), but the pgadmin docs aren't that complex - and probably shouldn't be. -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/
On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge <guillaume@lelarge.info> wrote: > Documentation for pgAdmin is really weak right now. Just to take an > example, I don't know where a plugin file is described. > > The real question is how we do this. Right now, the documentation is a > set of HTML files. Which is fine for some people and not for others. > Kind of hard to get a consistent style. Kind of hard to get a good PDF > and CHM file out of it. Not sure we really need these formats, I'm sure > we want a consistent style. > > The only way to get all these options, AFAICT, is to use Docbook. SGML > or XML. I have no problem working with Docbook, but I'm not sure > everyone feels the same. I really prefer XML because of the toolset we > can use (which seems, at least to me, in much better shape than the SGML > one). > > Anyone has better ideas? Yeah, I was looking at this the other day, but ran out of time. Looking at using Sphinx (http://sphinx.pocoo.org/). I really don't want to use SGML or XML. -- Dave Page Blog: http://pgsnake.blogspot.com Twitter: @pgsnake EnterpriseDB UK: http://www.enterprisedb.com The Enterprise Postgres Company
Le 24/09/2010 10:39, Dave Page a écrit : > On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge > <guillaume@lelarge.info> wrote: >> Documentation for pgAdmin is really weak right now. Just to take an >> example, I don't know where a plugin file is described. >> >> The real question is how we do this. Right now, the documentation is a >> set of HTML files. Which is fine for some people and not for others. >> Kind of hard to get a consistent style. Kind of hard to get a good PDF >> and CHM file out of it. Not sure we really need these formats, I'm sure >> we want a consistent style. >> >> The only way to get all these options, AFAICT, is to use Docbook. SGML >> or XML. I have no problem working with Docbook, but I'm not sure >> everyone feels the same. I really prefer XML because of the toolset we >> can use (which seems, at least to me, in much better shape than the SGML >> one). >> >> Anyone has better ideas? > > Yeah, I was looking at this the other day, but ran out of time. > Looking at using Sphinx (http://sphinx.pocoo.org/). > Seems interesting. Just at the same time, we (Dalibo) get rid of our documents in ReST format, so I'll still have to work with it for pgadmin :-/ Anyway, I need to test it a bit before going further on this. > I really don't want to use SGML or XML. > I supposed so :) -- Guillaume http://www.postgresql.fr http://dalibo.com
On Fri, Sep 24, 2010 at 11:16, Guillaume Lelarge <guillaume@lelarge.info> wrote: > Le 24/09/2010 10:39, Dave Page a écrit : >> On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge >> <guillaume@lelarge.info> wrote: >>> Documentation for pgAdmin is really weak right now. Just to take an >>> example, I don't know where a plugin file is described. >>> >>> The real question is how we do this. Right now, the documentation is a >>> set of HTML files. Which is fine for some people and not for others. >>> Kind of hard to get a consistent style. Kind of hard to get a good PDF >>> and CHM file out of it. Not sure we really need these formats, I'm sure >>> we want a consistent style. >>> >>> The only way to get all these options, AFAICT, is to use Docbook. SGML >>> or XML. I have no problem working with Docbook, but I'm not sure >>> everyone feels the same. I really prefer XML because of the toolset we >>> can use (which seems, at least to me, in much better shape than the SGML >>> one). >>> >>> Anyone has better ideas? >> >> Yeah, I was looking at this the other day, but ran out of time. >> Looking at using Sphinx (http://sphinx.pocoo.org/). >> > > Seems interesting. Just at the same time, we (Dalibo) get rid of our > documents in ReST format, so I'll still have to work with it for pgadmin :-/ Why do you get rid of ReST, and what are you changing to? -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/
Le 24/09/2010 11:59, Magnus Hagander a écrit : > On Fri, Sep 24, 2010 at 11:16, Guillaume Lelarge <guillaume@lelarge.info> wrote: >> Le 24/09/2010 10:39, Dave Page a écrit : >>> On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge >>> <guillaume@lelarge.info> wrote: >>>> Documentation for pgAdmin is really weak right now. Just to take an >>>> example, I don't know where a plugin file is described. >>>> >>>> The real question is how we do this. Right now, the documentation is a >>>> set of HTML files. Which is fine for some people and not for others. >>>> Kind of hard to get a consistent style. Kind of hard to get a good PDF >>>> and CHM file out of it. Not sure we really need these formats, I'm sure >>>> we want a consistent style. >>>> >>>> The only way to get all these options, AFAICT, is to use Docbook. SGML >>>> or XML. I have no problem working with Docbook, but I'm not sure >>>> everyone feels the same. I really prefer XML because of the toolset we >>>> can use (which seems, at least to me, in much better shape than the SGML >>>> one). >>>> >>>> Anyone has better ideas? >>> >>> Yeah, I was looking at this the other day, but ran out of time. >>> Looking at using Sphinx (http://sphinx.pocoo.org/). >>> >> >> Seems interesting. Just at the same time, we (Dalibo) get rid of our >> documents in ReST format, so I'll still have to work with it for pgadmin :-/ > > Why do you get rid of ReST, and what are you changing to? > Not really because of ReST. Our real issue was the tool we used to build HTML, PDF, etc. This tool was first written by dalibo, but nobody really maintains it and it became more and more difficult to install it on recent laptops. So, as you can see, not really an issue with ReST. And we are changing to... dokuwiki. You surely know Damien felt in love with this tool :) -- Guillaume http://www.postgresql.fr http://dalibo.com
Le 24/09/2010 12:06, Marek Černocký a écrit : > It would be nice to choice format the gettext (or similar tool) know > about. It's very difficult to track changes in the current documentation > for translators. > Gettext really doesn't work for documentation. It's much harder to know the context of each sentence. I'm translating the PostgreSQL manuel since 7.4.7 IIRC, and I'm completely against using a .po toolchain for the french translation. It could help to make it quicker and simpler to update, but it would quickly degrade the quality of the translation. Of course, this is only my opinion, and I know some that don't agree with me on this. -- Guillaume http://www.postgresql.fr http://dalibo.com
On Fri, Sep 24, 2010 at 11:13 AM, Guillaume Lelarge <guillaume@lelarge.info> wrote: > Not really because of ReST. Our real issue was the tool we used to build > HTML, PDF, etc. This tool was first written by dalibo, but nobody really > maintains it and it became more and more difficult to install it on > recent laptops. So, as you can see, not really an issue with ReST. And > we are changing to... dokuwiki. You surely know Damien felt in love with > this tool :) I know you're not suggesting it, but just so we're clear - the day pgAdmin starts to use docuwiki is the day that Microsoft release a Linux distro, Apple BSD licence all their code, pigs around the world spontaneously sprout wings and world peace is declared. When all those things happen at once, I'll gladly install docuwiki. :-p -- Dave Page Blog: http://pgsnake.blogspot.com Twitter: @pgsnake EnterpriseDB UK: http://www.enterprisedb.com The Enterprise Postgres Company
Le 24/09/2010 12:23, Dave Page a écrit : > On Fri, Sep 24, 2010 at 11:13 AM, Guillaume Lelarge > <guillaume@lelarge.info> wrote: >> Not really because of ReST. Our real issue was the tool we used to build >> HTML, PDF, etc. This tool was first written by dalibo, but nobody really >> maintains it and it became more and more difficult to install it on >> recent laptops. So, as you can see, not really an issue with ReST. And >> we are changing to... dokuwiki. You surely know Damien felt in love with >> this tool :) > > I know you're not suggesting it, but just so we're clear - the day > pgAdmin starts to use docuwiki is the day that Microsoft release a > Linux distro, Apple BSD licence all their code, pigs around the world > spontaneously sprout wings and world peace is declared. > > When all those things happen at once, I'll gladly install docuwiki. > > :-p > :-D (and yes, I'm not suggesting it) -- Guillaume http://www.postgresql.fr http://dalibo.com
On Fri, Sep 24, 2010 at 12:23, Dave Page <dpage@pgadmin.org> wrote: > On Fri, Sep 24, 2010 at 11:13 AM, Guillaume Lelarge > <guillaume@lelarge.info> wrote: >> Not really because of ReST. Our real issue was the tool we used to build >> HTML, PDF, etc. This tool was first written by dalibo, but nobody really >> maintains it and it became more and more difficult to install it on >> recent laptops. So, as you can see, not really an issue with ReST. And >> we are changing to... dokuwiki. You surely know Damien felt in love with >> this tool :) > > I know you're not suggesting it, but just so we're clear - the day > pgAdmin starts to use docuwiki is the day that Microsoft release a > Linux distro, Apple BSD licence all their code, pigs around the world > spontaneously sprout wings and world peace is declared. > > When all those things happen at once, I'll gladly install docuwiki. I think we should also require steve jobs to wear a suit during a presentation. -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/
On Fri, Sep 24, 2010 at 12:16 PM, Magnus Hagander <magnus@hagander.net> wrote: >> I know you're not suggesting it, but just so we're clear - the day >> pgAdmin starts to use docuwiki is the day that Microsoft release a >> Linux distro, Apple BSD licence all their code, pigs around the world >> spontaneously sprout wings and world peace is declared. >> >> When all those things happen at once, I'll gladly install docuwiki. > > I think we should also require steve jobs to wear a suit during a presentation. Well that just sets the barrier ridiculously high. There's no need to go over the top. -- Dave Page Blog: http://pgsnake.blogspot.com Twitter: @pgsnake EnterpriseDB UK: http://www.enterprisedb.com The Enterprise Postgres Company
I comprehend your concern for quality. But now I have no clear info about documentation changes. I would have to study git changelogs or do other frustration work. It has impact on documentation translation completeness and quality too. I translate Gnome (which uses own tools for work with documentation po/pot) and I don't see any problem with quality. Documentation translator is usually the same as UI translator so he has knowledge about application. I thing the limit to translation quality is translator at first, using .po is the matter in question. Guillaume Lelarge píše v Pá 24. 09. 2010 v 12:22 +0200: > Le 24/09/2010 12:06, Marek Černocký a écrit : > > It would be nice to choice format the gettext (or similar tool) know > > about. It's very difficult to track changes in the current documentation > > for translators. > > > > Gettext really doesn't work for documentation. It's much harder to know > the context of each sentence. I'm translating the PostgreSQL manuel > since 7.4.7 IIRC, and I'm completely against using a .po toolchain for > the french translation. It could help to make it quicker and simpler to > update, but it would quickly degrade the quality of the translation. Of > course, this is only my opinion, and I know some that don't agree with > me on this. > >
Le 24/09/2010 15:16, Marek Černocký a écrit : > I comprehend your concern for quality. But now I have no clear info > about documentation changes. I would have to study git changelogs or do > other frustration work. It has impact on documentation translation > completeness and quality too. > You just need this command: git diff REL-1_10_0_PATCHES -- docs/en_US Which gives you 439 lines of changes (many are from binary files). With this, you easily know changes on the documentation. > I translate Gnome (which uses own tools for work with documentation > po/pot) and I don't see any problem with quality. Documentation > translator is usually the same as UI translator so he has knowledge > about application. > Problem is not knowledge on the software. Translating a UI is a complete different business than translating a documentation. There's not really a context when you translate a UI, but there is one when you translate a manual. > I thing the limit to translation quality is translator at first, > using .po is the matter in question. > Anyway, there are tools that helps you to build .po files from various text formats. po4a for example. -- Guillaume http://www.postgresql.fr http://dalibo.com
Guillaume Lelarge píše v Pá 24. 09. 2010 v 16:20 +0200: > Le 24/09/2010 15:16, Marek Černocký a écrit : > > I comprehend your concern for quality. But now I have no clear info > > about documentation changes. I would have to study git changelogs or do > > other frustration work. It has impact on documentation translation > > completeness and quality too. > > > > You just need this command: > > git diff REL-1_10_0_PATCHES -- docs/en_US > > Which gives you 439 lines of changes (many are from binary files). With > this, you easily know changes on the documentation. > > > I translate Gnome (which uses own tools for work with documentation > > po/pot) and I don't see any problem with quality. Documentation > > translator is usually the same as UI translator so he has knowledge > > about application. > > > > Problem is not knowledge on the software. Translating a UI is a complete > different business than translating a documentation. There's not really > a context when you translate a UI, but there is one when you translate a > manual. Messages in .po file are sorted sequentially much like original document. And messages are full sentences or even paragraphs. Context you see directly. Documentation translation is exacting only for its length. Translating UI si difficult because you see isolated words or snippets and you must search context in application. > > I thing the limit to translation quality is translator at first, > > using .po is the matter in question. > > > > Anyway, there are tools that helps you to build .po files from various > text formats. po4a for example. > > > -- > Guillaume > http://www.postgresql.fr > http://dalibo.com >
Le 24/09/2010 11:16, Guillaume Lelarge a écrit : > Le 24/09/2010 10:39, Dave Page a écrit : >> On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge >> <guillaume@lelarge.info> wrote: >>> Documentation for pgAdmin is really weak right now. Just to take an >>> example, I don't know where a plugin file is described. >>> >>> The real question is how we do this. Right now, the documentation is a >>> set of HTML files. Which is fine for some people and not for others. >>> Kind of hard to get a consistent style. Kind of hard to get a good PDF >>> and CHM file out of it. Not sure we really need these formats, I'm sure >>> we want a consistent style. >>> >>> The only way to get all these options, AFAICT, is to use Docbook. SGML >>> or XML. I have no problem working with Docbook, but I'm not sure >>> everyone feels the same. I really prefer XML because of the toolset we >>> can use (which seems, at least to me, in much better shape than the SGML >>> one). >>> >>> Anyone has better ideas? >> >> Yeah, I was looking at this the other day, but ran out of time. >> Looking at using Sphinx (http://sphinx.pocoo.org/). >> > > Seems interesting. Just at the same time, we (Dalibo) get rid of our > documents in ReST format, so I'll still have to work with it for pgadmin :-/ > > Anyway, I need to test it a bit before going further on this. > Seems good to me. See http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html. It took me three hours to manually convert the current documentation. There is also a possibility to change the theme. I'll try to do it on my laptop. -- Guillaume http://www.postgresql.fr http://dalibo.com
On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge <guillaume@lelarge.info> wrote: > > See > http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html. > > It took me three hours to manually convert the current documentation. > There is also a possibility to change the theme. I'll try to do it on my > laptop. Wow, that was quick (and unexpected!). There's some weirdness here, but maybe that's just a markup issue: http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect --- If you select “Store password”, pgAdmin stores passwords you enter in the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf --- Otherwise it looks great. Couple of questions: - Have you thought about how we might shoe-horn this into the build process? - Have you tried the htmlhelp output on Windows and Linux/Mac? -- Dave Page Blog: http://pgsnake.blogspot.com Twitter: @pgsnake EnterpriseDB UK: http://www.enterprisedb.com The Enterprise Postgres Company
On Mon, Sep 27, 2010 at 10:00, Dave Page <dpage@pgadmin.org> wrote: > On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge > <guillaume@lelarge.info> wrote: >> >> See >> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html. >> >> It took me three hours to manually convert the current documentation. >> There is also a possibility to change the theme. I'll try to do it on my >> laptop. > > Wow, that was quick (and unexpected!). There's some weirdness here, Indeed. Nice job! > but maybe that's just a markup issue: > > http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect I notice some weirdness on http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/pgagent-install.html as well: 1) I get scrollbars on all the "highlighted areas", that scrolls exactly 1 pixel. Probably a CSS issue? 2) If I do view source to figure out why, I notice they have class "highlight-python" - is there something that should be set to make it not call it python? (I haven't investigated what it actually means yet, no :P) > Otherwise it looks great. Couple of questions: > > - Have you thought about how we might shoe-horn this into the build process? One direct question here - is it going to be a PITA on Windows? I've never tried it there, it might be? -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/
On 27 September 2010 09:00, Dave Page <dpage@pgadmin.org> wrote: > On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge > <guillaume@lelarge.info> wrote: >> >> See >> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html. >> >> It took me three hours to manually convert the current documentation. >> There is also a possibility to change the theme. I'll try to do it on my >> laptop. > > Wow, that was quick (and unexpected!). There's some weirdness here, > but maybe that's just a markup issue: > > http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect > > --- > If you select “Store password”, pgAdmin stores passwords you enter in > the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf > --- That's because those paragraphs are justified. Just alter the css to use "text-align: left;" instead. -- Thom Brown Twitter: @darkixion IRC (freenode): dark_ixion Registered Linux user: #516935
On 27 September 2010 09:06, Magnus Hagander <magnus@hagander.net> wrote: > On Mon, Sep 27, 2010 at 10:00, Dave Page <dpage@pgadmin.org> wrote: >> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge >> <guillaume@lelarge.info> wrote: >>> >>> See >>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html. >>> >>> It took me three hours to manually convert the current documentation. >>> There is also a possibility to change the theme. I'll try to do it on my >>> laptop. >> >> Wow, that was quick (and unexpected!). There's some weirdness here, > > Indeed. Nice job! > > >> but maybe that's just a markup issue: >> >> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect > > I notice some weirdness on > http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/pgagent-install.html > as well: > > 1) I get scrollbars on all the "highlighted areas", that scrolls > exactly 1 pixel. Probably a CSS issue? If you remove the ability to scroll the overflow, text on some pages, or small screens, will flow outside the container. > 2) If I do view source to figure out why, I notice they have class > "highlight-python" - is there something that should be set to make it > not call it python? (I haven't investigated what it actually means > yet, no :P) The highlight-python class has no bearing on style as nothing refers to that class in any CSS file. You can safely rename it, but it will have no visual effect. But great work Guillaume :) Very slick. And I see you've also updated the screenshots too, so it includes the mystery history box! :D (although no textual references to it ATM) -- Thom Brown Twitter: @darkixion IRC (freenode): dark_ixion Registered Linux user: #516935
On Mon, Sep 27, 2010 at 9:11 AM, Thom Brown <thom@linux.com> wrote: > On 27 September 2010 09:00, Dave Page <dpage@pgadmin.org> wrote: >> Wow, that was quick (and unexpected!). There's some weirdness here, >> but maybe that's just a markup issue: >> >> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect >> >> --- >> If you select “Store password”, pgAdmin stores passwords you enter in >> the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf >> --- > > That's because those paragraphs are justified. Just alter the css to > use "text-align: left;" instead. I'm referring to the missing /'s, though the justification does look a little odd on that line too (for the reason you state). -- Dave Page Blog: http://pgsnake.blogspot.com Twitter: @pgsnake EnterpriseDB UK: http://www.enterprisedb.com The Enterprise Postgres Company
On 27 September 2010 09:26, Dave Page <dpage@pgadmin.org> wrote: > On Mon, Sep 27, 2010 at 9:11 AM, Thom Brown <thom@linux.com> wrote: >> On 27 September 2010 09:00, Dave Page <dpage@pgadmin.org> wrote: >>> Wow, that was quick (and unexpected!). There's some weirdness here, >>> but maybe that's just a markup issue: >>> >>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect >>> >>> --- >>> If you select “Store password”, pgAdmin stores passwords you enter in >>> the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf >>> --- >> >> That's because those paragraphs are justified. Just alter the css to >> use "text-align: left;" instead. > > I'm referring to the missing /'s, though the justification does look a > little odd on that line too (for the reason you state). Oh yeah! Yes, nothing to do with CSS there. :) Might be something to do with it automatically turning it into a link, but doesn't like backslashes. -- Thom Brown Twitter: @darkixion IRC (freenode): dark_ixion Registered Linux user: #516935
Hi I wrote a PostgreSQL syntax highlighting [1] for Pygments (used by sphinx for code) I don't know if it may be useful for the documentation. Regards, [1] : https://bitbucket.org/kryskool/pygments-postgresql/ On Sun, 26 Sep 2010 22:50:19 +0200, Guillaume Lelarge <guillaume@lelarge.info> wrote: > Le 24/09/2010 11:16, Guillaume Lelarge a écrit : >> Le 24/09/2010 10:39, Dave Page a écrit : >>> On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge >>> <guillaume@lelarge.info> wrote: >>>> Documentation for pgAdmin is really weak right now. Just to take an >>>> example, I don't know where a plugin file is described. >>>> >>>> The real question is how we do this. Right now, the documentation is a >>>> set of HTML files. Which is fine for some people and not for others. >>>> Kind of hard to get a consistent style. Kind of hard to get a good PDF >>>> and CHM file out of it. Not sure we really need these formats, I'm > sure >>>> we want a consistent style. >>>> >>>> The only way to get all these options, AFAICT, is to use Docbook. SGML >>>> or XML. I have no problem working with Docbook, but I'm not sure >>>> everyone feels the same. I really prefer XML because of the toolset we >>>> can use (which seems, at least to me, in much better shape than the > SGML >>>> one). >>>> >>>> Anyone has better ideas? >>> >>> Yeah, I was looking at this the other day, but ran out of time. >>> Looking at using Sphinx (http://sphinx.pocoo.org/). >>> >> >> Seems interesting. Just at the same time, we (Dalibo) get rid of our >> documents in ReST format, so I'll still have to work with it for pgadmin > :-/ >> >> Anyway, I need to test it a bit before going further on this. >> > > Seems good to me. > > See > http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html. > > It took me three hours to manually convert the current documentation. > There is also a possibility to change the theme. I'll try to do it on my > laptop. > > > -- > Guillaume > http://www.postgresql.fr > http://dalibo.com > > -- > Sent via pgadmin-hackers mailing list (pgadmin-hackers@postgresql.org) > To make changes to your subscription: > http://www.postgresql.org/mailpref/pgadmin-hackers
Le 27/09/2010 10:00, Dave Page a écrit : > On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge > <guillaume@lelarge.info> wrote: >> >> See >> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html. >> >> It took me three hours to manually convert the current documentation. >> There is also a possibility to change the theme. I'll try to do it on my >> laptop. > > Wow, that was quick (and unexpected!). There's some weirdness here, > but maybe that's just a markup issue: > > http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect > > --- > If you select “Store password”, pgAdmin stores passwords you enter in > the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf > --- > Yes, there are probably a lot of weirdness. Not because of the tool, but because of me. I think it would be hard for me to work on this before this weekend. Crappy hotel (and when I say crappy, I really mean it... or probably worse), and crappy internet connection. > Otherwise it looks great. Couple of questions: > > - Have you thought about how we might shoe-horn this into the build process? > Not yet. Actually, my main issue is "what should we put on the repo?". Only the .rst files? the whole project, including the Makefile? I didn't set my mind yet on this issue. > - Have you tried the htmlhelp output on Windows and Linux/Mac? > Not yet :) I'm waiting to have a windows box before working on this (ie get back to my home). -- Guillaume http://www.postgresql.fr http://dalibo.com
Le 27/09/2010 10:06, Magnus Hagander a écrit : > On Mon, Sep 27, 2010 at 10:00, Dave Page <dpage@pgadmin.org> wrote: >> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge >> <guillaume@lelarge.info> wrote: >>> >>> See >>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html. >>> >>> It took me three hours to manually convert the current documentation. >>> There is also a possibility to change the theme. I'll try to do it on my >>> laptop. >> >> Wow, that was quick (and unexpected!). There's some weirdness here, > > Indeed. Nice job! > Thanks. >> but maybe that's just a markup issue: >> >> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect > > I notice some weirdness on > http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/pgagent-install.html > as well: > > 1) I get scrollbars on all the "highlighted areas", that scrolls > exactly 1 pixel. Probably a CSS issue? > 2) If I do view source to figure out why, I notice they have class > "highlight-python" - is there something that should be set to make it > not call it python? (I haven't investigated what it actually means > yet, no :P) > Well, actually, I think we should have a customized theme, so that the docs look like our website. >> Otherwise it looks great. Couple of questions: >> >> - Have you thought about how we might shoe-horn this into the build process? > > One direct question here - is it going to be a PITA on Windows? I've > never tried it there, it might be? > Shouldn't be. I didn't ask for it, but you can have a .bat file to build the documentation. Of course, next question is: "is it going to be a PITA to install python and its plugins on Windows?" I don't have an answer on this one. -- Guillaume http://www.postgresql.fr http://dalibo.com
Le 27/09/2010 10:17, Thom Brown a écrit : > On 27 September 2010 09:06, Magnus Hagander <magnus@hagander.net> wrote: >> On Mon, Sep 27, 2010 at 10:00, Dave Page <dpage@pgadmin.org> wrote: >>> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge >>> <guillaume@lelarge.info> wrote: >>>> >>>> See >>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html. >>>> >>>> It took me three hours to manually convert the current documentation. >>>> There is also a possibility to change the theme. I'll try to do it on my >>>> laptop. >>> >>> Wow, that was quick (and unexpected!). There's some weirdness here, >> >> Indeed. Nice job! >> >> >>> but maybe that's just a markup issue: >>> >>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect >> >> I notice some weirdness on >> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/pgagent-install.html >> as well: >> >> 1) I get scrollbars on all the "highlighted areas", that scrolls >> exactly 1 pixel. Probably a CSS issue? > > If you remove the ability to scroll the overflow, text on some pages, > or small screens, will flow outside the container. > >> 2) If I do view source to figure out why, I notice they have class >> "highlight-python" - is there something that should be set to make it >> not call it python? (I haven't investigated what it actually means >> yet, no :P) > > The highlight-python class has no bearing on style as nothing refers > to that class in any CSS file. You can safely rename it, but it will > have no visual effect. > It could have an effect with other tags. I didn't use every tag that sphinx allows. > But great work Guillaume :) Very slick. Thanks :) > And I see you've also > updated the screenshots too, so it includes the mystery history box! > :D (although no textual references to it ATM) > The screenshots should be updated on the current website too. -- Guillaume http://www.postgresql.fr http://dalibo.com
Le 27/09/2010 10:42, Thom Brown a écrit : > On 27 September 2010 09:26, Dave Page <dpage@pgadmin.org> wrote: >> On Mon, Sep 27, 2010 at 9:11 AM, Thom Brown <thom@linux.com> wrote: >>> On 27 September 2010 09:00, Dave Page <dpage@pgadmin.org> wrote: >>>> Wow, that was quick (and unexpected!). There's some weirdness here, >>>> but maybe that's just a markup issue: >>>> >>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect >>>> >>>> --- >>>> If you select “Store password”, pgAdmin stores passwords you enter in >>>> the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf >>>> --- >>> >>> That's because those paragraphs are justified. Just alter the css to >>> use "text-align: left;" instead. >> >> I'm referring to the missing /'s, though the justification does look a >> little odd on that line too (for the reason you state). > > Oh yeah! Yes, nothing to do with CSS there. :) Might be something to > do with it automatically turning it into a link, but doesn't like > backslashes. > Will fix it in a few days. -- Guillaume http://www.postgresql.fr http://dalibo.com
On Mon, Sep 27, 2010 at 18:26, Guillaume Lelarge <guillaume@lelarge.info> wrote: > Le 27/09/2010 10:06, Magnus Hagander a écrit : >> On Mon, Sep 27, 2010 at 10:00, Dave Page <dpage@pgadmin.org> wrote: >>> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge >>> <guillaume@lelarge.info> wrote: >>>> >>>> See >>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html. >>>> >>>> It took me three hours to manually convert the current documentation. >>>> There is also a possibility to change the theme. I'll try to do it on my >>>> laptop. >>> >>> Wow, that was quick (and unexpected!). There's some weirdness here, >> >> Indeed. Nice job! >> > > Thanks. > >>> but maybe that's just a markup issue: >>> >>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect >> >> I notice some weirdness on >> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/pgagent-install.html >> as well: >> >> 1) I get scrollbars on all the "highlighted areas", that scrolls >> exactly 1 pixel. Probably a CSS issue? >> 2) If I do view source to figure out why, I notice they have class >> "highlight-python" - is there something that should be set to make it >> not call it python? (I haven't investigated what it actually means >> yet, no :P) >> > > Well, actually, I think we should have a customized theme, so that the > docs look like our website. +1. >>> Otherwise it looks great. Couple of questions: >>> >>> - Have you thought about how we might shoe-horn this into the build process? >> >> One direct question here - is it going to be a PITA on Windows? I've >> never tried it there, it might be? >> > > Shouldn't be. I didn't ask for it, but you can have a .bat file to build > the documentation. Of course, next question is: "is it going to be a > PITA to install python and its plugins on Windows?" I don't have an > answer on this one. Well, that's really what was my question :-) -- Magnus Hagander Me: http://www.hagander.net/ Work: http://www.redpill-linpro.com/