public inbox for [email protected]
help / color / mirror / Atom feedFrom: Marti Raudsepp <[email protected]>
To: pgsql-www <[email protected]>
Cc: Andres Freund <[email protected]>
Cc: Stefan Kaltenbrunner <[email protected]>
Subject: [PATCH] Cross-version navigation in documentation
Date: Sun, 27 May 2012 21:06:03 +0300
Message-ID: <CABRT9RCFpt35TdrrN0jsY3YfqMiiJOTTWYWpSQKYaEdcQZKugw@mail.gmail.com> (raw)
Hi list,
It always bothers me that Google links to version-specific PostgreSQL
documentation pages, usually an obsolete version. This patch lets you
easily navigate to the version you want by adding a new line at the
top:
This page in other versions: 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 /
8.0 / 7.4 / 7.3 / 7.2 / devel
The same page in different versions is assumed to have the same file
name. No effort is done to track pages which have been
removed/added/split/renamed -- I think that would be lots of
complexity for little gain. For example, The 7.4 version contains 644
doc pages, and only 68 of those (~10%) aren't present in 9.2. In
actual relevant versions, the overlap is much greater.
I also noticed that the docs table isn't currently indexed at all.
docs/models.py now defines a new index/unique constraint, which
requires manual migration:
alter table docs add unique (file, version);
PS: Python projects have a nearly universal style of using 4-space
indents (PEP-0008). I understand that PostgreSQL itself uses tabs, but
maybe a change is warranted here, since Python is particularly picky
about indentation?
----
Attached are two patches:
0001-Allow-documentation-loading-without-tidy-Tidylib-for.patch
Just a simple fallback so docs can be imported without µTidylib --
which is not packaged for Arch Linux
0002-Add-basic-version-navigation-support-for-documentati.patch
Actual implementation of cross-version navigation
Also available from my github fork: https://github.com/intgr/pgweb
Regards,
Marti
Attachments:
[application/octet-stream] 0001-Allow-documentation-loading-without-tidy-Tidylib-for.patch (1.4K, 2-0001-Allow-documentation-loading-without-tidy-Tidylib-for.patch)
download | inline diff:
From 1eca1859a9cc41b2cdf890c7b236752aff7811a3 Mon Sep 17 00:00:00 2001
From: Marti Raudsepp <[email protected]>
Date: Sat, 26 May 2012 03:25:46 +0300
Subject: [PATCH 1/2] =?UTF-8?q?Allow=20documentation=20loading=20without=20t?=
=?UTF-8?q?idy=20(=C2=B5Tidylib)=20for=20development?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
tools/docs/docload.py | 14 +++++++++++---
1 file changed, 11 insertions(+), 3 deletions(-)
diff --git a/tools/docs/docload.py b/tools/docs/docload.py
index c88df7e..e1c0ec4 100755
--- a/tools/docs/docload.py
+++ b/tools/docs/docload.py
@@ -6,7 +6,11 @@ import sys
import os
import tarfile
import re
-import tidy
+try:
+ import tidy
+except ImportError, err:
+ print>>sys.stderr, "WARNING: cannot import tidy: %s" % err
+ tidy = None
from optparse import OptionParser
@@ -43,12 +47,16 @@ def load_doc_file(filename, f):
title = ""
if not quiet: print "--- file: %s (%s) ---" % (filename, title)
- s = tidy.parseString(contents.encode('utf-8'), **tidyopts)
+ if tidy:
+ s = str(tidy.parseString(contents.encode('utf-8'), **tidyopts))
+ else:
+ s = contents
+
curs.execute("INSERT INTO docs (file, version, title, content) VALUES (%(f)s, %(v)s, %(t)s, %(c)s)",{
'f': filename,
'v': ver,
't': title,
- 'c': str(s),
+ 'c': s,
})
global pagecount
pagecount += 1
--
1.7.10.2
[application/octet-stream] 0002-Add-basic-version-navigation-support-for-documentati.patch (5.4K, 3-0002-Add-basic-version-navigation-support-for-documentati.patch)
download | inline diff:
From baaef6860f6ef950d8fce0e346d4f922aba0fb91 Mon Sep 17 00:00:00 2001
From: Marti Raudsepp <[email protected]>
Date: Sat, 26 May 2012 03:29:02 +0300
Subject: [PATCH 2/2] Add basic version navigation support for documentation
Also refactored "devel" version display logic into
DocPage.display_version function.
Requires database modification:
alter table docs add unique (file, version);
---
media/css/docs.css | 2 +-
pgweb/docs/models.py | 9 +++++++++
pgweb/docs/views.py | 8 +++++---
templates/docs/docspage.html | 17 ++++++++++++++---
4 files changed, 29 insertions(+), 7 deletions(-)
diff --git a/media/css/docs.css b/media/css/docs.css
index 24857b0..3b272f6 100644
--- a/media/css/docs.css
+++ b/media/css/docs.css
@@ -51,7 +51,7 @@ div.NAVHEADER table {
padding-bottom: 2px;
}
-#docNav {
+#docNav, #docVersions {
position: relative;
text-align: left;
margin-left: 10px;
diff --git a/pgweb/docs/models.py b/pgweb/docs/models.py
index 4aafde4..5ea1497 100644
--- a/pgweb/docs/models.py
+++ b/pgweb/docs/models.py
@@ -12,8 +12,17 @@ class DocPage(models.Model):
title = models.CharField(max_length=256, null=True, blank=True)
content = models.TextField(null=True, blank=True)
+ def display_version(self):
+ """Version as used for displaying and in URLs"""
+ if self.version == 0:
+ return 'devel'
+ else:
+ return str(self.version)
+
class Meta:
db_table = 'docs'
+ # Index file first, because we want to list versions by file
+ unique_together = [('file', 'version')]
class DocComment(PgModel, models.Model):
version = models.DecimalField(max_digits=3, decimal_places=1, null=False)
diff --git a/pgweb/docs/views.py b/pgweb/docs/views.py
index d5969a8..aaafd1d 100644
--- a/pgweb/docs/views.py
+++ b/pgweb/docs/views.py
@@ -41,17 +41,19 @@ def docpage(request, version, typ, filename):
else:
indexname = "index.html"
- page = get_object_or_404(DocPage, version=ver, file="%s.%s" % (filename, extension))
+ fullname = "%s.%s" % (filename, extension)
+ page = get_object_or_404(DocPage, version=ver, file=fullname)
+ versions = DocPage.objects.filter(file=fullname).order_by('-version').only('version', 'file')
if typ=="interactive":
- comments = DocComment.objects.filter(version=ver, file="%s.%s" % (filename, extension), approved=True).order_by('posted_at')
+ comments = DocComment.objects.filter(version=ver, file=fullname, approved=True).order_by('posted_at')
else:
comments = None
return render_to_response('docs/docspage.html', {
'page': page,
+ 'versions': versions,
'title': page.title,
- 'doc_nav_version': ver > 0 and ver or "devel",
'doc_type': typ,
'comments': comments,
'can_comment': (typ=="interactive" and ver==currver),
diff --git a/templates/docs/docspage.html b/templates/docs/docspage.html
index d68dafe..2727562 100644
--- a/templates/docs/docspage.html
+++ b/templates/docs/docspage.html
@@ -1,7 +1,7 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en" dir="ltr">
<head>
- <title>PostgreSQL: Documentation: {{doc_nav_version}}: {{page.title}}</title>
+ <title>PostgreSQL: Documentation: {{page.display_version}}: {{page.title}}</title>
<style type="text/css" media="screen" title="Normal Text">@import url("/media/css/docs.css");</style>
<link rel="alternate stylesheet" media="screen" href="/media/css/docs_large.css" type="text/css" title="Large Text" />
<script type="text/javascript" src="/media/js/styleswitcher.js"></script>
@@ -30,14 +30,25 @@
<div id="docSearch">
<form action="/search/" method="get">
<div>
- <input type="hidden" name="u" value="/docs/{{doc_nav_version}}/">
+ <input type="hidden" name="u" value="/docs/{{page.display_version}}/">
<label for="q">Search Documentation: </label><input type="text" id="q" name="q" size="20" onfocus="if( this.value==this.defaultValue ) this.value='';" value="Search" /><input id="submit" type="submit" value="Search" />
</div>
</form>
<div id="docTextSize">Text Size: <a href="#" onclick="setActiveStyleSheet('Normal Text'); return false;" onkeypress="return false;" title="Normal Text Size">Normal</a> / <a href="#" onclick="setActiveStyleSheet('Large Text'); return false;" onkeypress="return false;" title="Large Text Size">Large</a></div>
</div>
<div id="docNav">
-<a href="/" title="Home">Home</a> → <a href="/docs" title="Documentation">Documentation</a> → <a href="/docs/manuals" title="Manuals">Manuals</a> → <a href="/docs/{{doc_nav_version}}/{{doc_type}}/{{doc_index_filename}}">PostgreSQL {{doc_nav_version}}</a>{%if loaddate%} ({{loaddate|date:"Y-m-d H:i:s"}}){%endif%}
+<a href="/" title="Home">Home</a> → <a href="/docs" title="Documentation">Documentation</a> → <a href="/docs/manuals" title="Manuals">Manuals</a> → <a href="/docs/{{page.display_version}}/{{doc_type}}/{{doc_index_filename}}">PostgreSQL {{page.display_version}}</a>{%if loaddate%} ({{loaddate|date:"Y-m-d H:i:s"}}){%endif%}
+</div>
+<div id="docVersions">
+This page in other versions:
+{% for ver in versions %}
+ {% if not forloop.first %}/{% endif %}
+ {% if ver.version == page.version %}
+ <b>{{ver.display_version}}</b>
+ {% else %}
+ <a href="/docs/{{ver.display_version}}/{{doc_type}}/{{ver.file}}" title="This page in version {{ver.display_version}}">{{ver.display_version}}</a>
+ {% endif %}
+{% endfor %}
</div>
</div>
--
1.7.10.2
view thread (14+ messages) latest in thread
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected]
Subject: Re: [PATCH] Cross-version navigation in documentation
In-Reply-To: <CABRT9RCFpt35TdrrN0jsY3YfqMiiJOTTWYWpSQKYaEdcQZKugw@mail.gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox