Replace interactive docs with docs bug reporting

Per discussion from a long time ago, interactive docs aren't really
working out. The majority of submissions are either support questions
(which then get rejected because they cannot be answered in this
context) or pointing out docs incorrectnesses (which should be submitted
as a docs bug instead, so they can actually be fixed in the main
documentation).

Old references to /interactive/ will get redirected to /static/
automatically, and we expect to keep doing that for a long time (since
there are many links to them around the net).

pgweb/docs/admin.py

@@ -1,17 +1,2 @@
 from django.contrib import admin
-from models import DocComment
 
-def approve_doccomment(modeladmin, request, queryset):
-	# We need to do this in a loop even though it's less efficient,
-	# since using queryset.update() will not send the moderation messages.
-	for e in queryset:
-		e.approved = True
-		e.save()
-approve_doccomment.short_description = 'Approve comment'
-
-class DocCommentAdmin(admin.ModelAdmin):
-	list_display = ('file', 'version', 'posted_at', 'approved', )
-	list_filter = ('approved', )
-	actions = [approve_doccomment, ]
-
-admin.site.register(DocComment, DocCommentAdmin)

pgweb/docs/forms.py

@@ -1,9 +1,8 @@
 from django import forms
 
-from models import DocComment
-
-class DocCommentForm(forms.ModelForm):
-	class Meta:
-		model = DocComment
-		exclude = ('submitter', 'approved', 'version', 'file', 'posted_at', )
-
+class DocCommentForm(forms.Form):
+	name = forms.CharField(max_length=100, required=True)
+	email = forms.EmailField(max_length=100, required=True)
+	shortdesc = forms.CharField(max_length=100, required=True,
+								label="Short description")
+	details = forms.CharField(required=True, widget=forms.Textarea)

pgweb/docs/migrations/0002_drop_doccomments.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+from __future__ import unicode_literals
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('docs', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name='doccomment',
+            name='submitter',
+        ),
+        migrations.DeleteModel(
+            name='DocComment',
+        ),
+    ]

pgweb/docs/models.py

@@ -20,34 +20,3 @@ class DocPage(models.Model):
 		db_table = 'docs'
 		# Index file first, because we want to list versions by file
 		unique_together = [('file', 'version')]
-
-class DocComment(models.Model):
-	version = models.DecimalField(max_digits=3, decimal_places=1, null=False)
-	file = models.CharField(max_length=64, null=False, blank=False)
-	comment = models.TextField(null=False, blank=False)
-	posted_at = models.DateTimeField(null=False, blank=False, auto_now_add=True)
-	submitter = models.ForeignKey(User, null=False)
-	approved = models.BooleanField(blank=False, default=False)
-
-	send_notification = True
-
-	def purge_urls(self):
-		yield '/docs/%s/interactive/%s' % (self.version, self.file)
-		try:
-			if Version.objects.get(tree=self.version).current:
-				yield '/docs/current/interactive/%s' % self.file
-		except Version.DoesNotExist:
-			pass
-
-	class Meta:
-		ordering = ('-posted_at',)
-
-	@property
-	def poster(self):
-		if self.submitter_id > 0:
-			return "%s %s" % (self.submitter.first_name, self.submitter.last_name)
-		else:
-			return ''
-
-	def __unicode__(self):
-		return "%s ver %s: %s" % (self.file, self.version, self.comment[:50])

pgweb/docs/views.py

@@ -1,5 +1,6 @@
 from django.shortcuts import render_to_response, get_object_or_404
-from django.http import HttpResponseRedirect, Http404
+from django.http import HttpResponseRedirect, HttpResponsePermanentRedirect
+from django.http import Http404
 from django.template.context import RequestContext
 from django.contrib.auth.decorators import login_required
 from django.db.models import Q
@@ -10,11 +11,12 @@ import os
 
 from pgweb.util.decorators import ssl_required
 from pgweb.util.contexts import NavContext
-from pgweb.util.helpers import simple_form
+from pgweb.util.helpers import template_to_string
+from pgweb.util.misc import send_template_mail
 
 from pgweb.core.models import Version
 
-from models import DocPage, DocComment
+from models import DocPage
 from forms import DocCommentForm
 
 def docpage(request, version, typ, filename):
@@ -54,9 +56,8 @@ def docpage(request, version, typ, filename):
 	}).order_by('-supported', '-version').only('version', 'file')
 
 	if typ=="interactive":
-		comments = DocComment.objects.filter(version=ver, file=fullname, approved=True).order_by('posted_at')
-	else:
-		comments = None
+		# Interactive documents are disabled, so redirect to static page
+		return HttpResponsePermanentRedirect("/docs/{0}/static/{1}.html".format(version, filename))
 
 	return render_to_response('docs/docspage.html', {
 		'page': page,
@@ -64,9 +65,6 @@ def docpage(request, version, typ, filename):
 		'devel_versions': [v for v in versions if not v.supported and v.testing],
 		'unsupported_versions': [v for v in versions if not v.supported and not v.testing],
 		'title': page.title,
-		'doc_type': typ,
-		'comments': comments,
-		'can_comment': (typ=="interactive" and ver==currver),
 		'doc_index_filename': indexname,
 		'loaddate': loaddate,
 	}, RequestContext(request))
@@ -124,10 +122,33 @@ def manualarchive(request):
 @ssl_required
 @login_required
 def commentform(request, itemid, version, filename):
-	return simple_form(DocComment, itemid, request, DocCommentForm,
-		fixedfields={
+	if request.method == 'POST':
+		form = DocCommentForm(request.POST)
+		if form.is_valid():
+			send_template_mail(
+				form.cleaned_data['email'],
+				settings.DOCSREPORT_EMAIL,
+				'%s' % form.cleaned_data['shortdesc'],
+				'docs/docsbugmail.txt', {
 					'version': version,
-			'file': filename,
+					'filename': filename,
+					'details': form.cleaned_data['details'],
 				},
-		redirect='/docs/comment_submitted/'
+				usergenerated=True,
 			)
+			return render_to_response('docs/docsbug_completed.html', {
+			}, NavContext(request, 'docs'))
+	else:
+		form = DocCommentForm(initial={
+			'name': '%s %s' % (request.user.first_name, request.user.last_name),
+			'email': request.user.email,
+		})
+
+	return render_to_response('base/form.html', {
+		'form': form,
+		'formitemtype': 'documentation correction',
+		'operation': 'Submit',
+		'form_intro': template_to_string('docs/docsbug.html', {
+			'user': request.user,
+		}),
+	}, NavContext(request, 'docs'))

pgweb/settings.py

@@ -157,6 +157,7 @@ NOTIFICATION_EMAIL="someone@example.com"               # Address to send notific
 NOTIFICATION_FROM="someone@example.com"                # Address to send notifications *from*
 LISTSERVER_EMAIL="someone@example.com"                 # Address to majordomo
 BUGREPORT_EMAIL="someone@example.com"                  # Address to pgsql-bugs list
+DOCSREPORT_EMAIL="someone@example.com"                 # Address to pgsql-docs list
 NO_HTTPS_REDIRECT=False                                # Set to true to disable redirects to https when
                                                        # developing locally
 FRONTEND_SERVERS=()                                    # A tuple containing the *IP addresses* of all the

pgweb/util/moderation.py

@@ -2,7 +2,6 @@
 from pgweb.news.models import NewsArticle
 from pgweb.events.models import Event
 from pgweb.core.models import Organisation
-from pgweb.docs.models import DocComment
 from pgweb.downloads.models import Product
 from pgweb.profserv.models import ProfessionalService
 from pgweb.quotes.models import Quote
@@ -20,7 +19,6 @@ def get_all_pending_moderations():
 		_get_unapproved_list(NewsArticle),
 		_get_unapproved_list(Event),
 		_get_unapproved_list(Organisation),
-		_get_unapproved_list(DocComment),
 		_get_unapproved_list(Product),
 		_get_unapproved_list(ProfessionalService),
 		_get_unapproved_list(Quote),

templates/docs/archive.html

@@ -10,17 +10,15 @@ If you are still using any of these releases, you are strongly advised to upgrad
 <div class="tblBasic">
 <table border="0" cellpadding="0" cellspacing="0" class="tblBasicGrey">
 <tr>
-	<th class="colFirst">Release</th>
 	<th class="colMid">Online Version</th>
 	<th class="colLast">PDF Version</th>
 </tr>
 
 {%for v in versions%}
 <tr{%if forloop.last%} class="lastrow"{%endif%}>
-    <td class="colFirst">{{v.tree}}</td>
     <td class="colMid">
           <ul>
-              <li><a href="/docs/{{v.tree}}/static/{{v.indexname}}">Without user comments</a></li>
+            <li><a href="/docs/{{v.tree}}/static/index.html">{{v.treestring}}</a></li>
           </ul>
       </td>
       <td class="colLast">

templates/docs/docsbug.html

@@ -0,0 +1,4 @@
+Filling out this email form will generate an email from
+{{user.email}} and post this to a the public pgsql-docs
+<a href="/list/">mailinglist</a>. Excpect further discussions
+to happen on this list after the submission is done.

templates/docs/docsbug_completed.html

@@ -0,0 +1,10 @@
+{%extends "base/page.html"%}
+{%block title%}Documentation comment{%endblock%}
+{%block contents%}
+<h1>Documentation comment</h1>
+<p>
+Your documentation comment has been received, and been posted to
+the <a href="/list/pgsql-docs/">pgsql-docs</a> mailinglist. It will
+show up there as soon as it has cleared the moderator queue.
+</p>
+{%endblock%}

templates/docs/docsbugmail.txt

@@ -0,0 +1,6 @@
+The following documentation comment has been logged on the website:
+
+Page: http://www.postgresql.org/docs/{{version}}/static/{{filename}}
+Description:
+
+{{details|wordwrap:76}}

templates/docs/docspage.html

@@ -34,7 +34,7 @@
 	</form>
 </div>
 <div id="docNav">
-<a href="/" title="Home">Home</a> &rarr; <a href="/docs" title="Documentation">Documentation</a> &rarr; <a href="/docs/manuals" title="Manuals">Manuals</a> &rarr; <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%}
+<a href="/" title="Home">Home</a> &rarr; <a href="/docs" title="Documentation">Documentation</a> &rarr; <a href="/docs/manuals" title="Manuals">Manuals</a> &rarr; <a href="/docs/{{page.display_version}}/static/{{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:
@@ -45,14 +45,14 @@ This page in other versions:
 		{%if ver.version == page.version %}
 		current ({{ver.display_version}})
 		{%else%}
-		<a href="/docs/current/{{doc_type}}/{{ver.file}}" title="This page in version {{ver.display_version}}">current</a>
-		(<a href="/docs/{{ver.display_version}}/{{doc_type}}/{{ver.file}}" title="This page in current version">{{ver.display_version}}</a>)
+		<a href="/docs/current/static/{{ver.file}}" title="This page in version {{ver.display_version}}">current</a>
+		(<a href="/docs/{{ver.display_version}}/static/{{ver.file}}" title="This page in current version">{{ver.display_version}}</a>)
 		{%endif%}
 	{%else%}
 		{%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>
+		<a href="/docs/{{ver.display_version}}/static/{{ver.file}}" title="This page in version {{ver.display_version}}">{{ver.display_version}}</a>
 		{%endif%}
 	{%endif%}
 {%endfor%}
@@ -65,7 +65,7 @@ This page in other versions:
 	{%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}}" rel="nofollow">{{ver.display_version}}</a>
+	<a href="/docs/{{ver.display_version}}/static/{{ver.file}}" title="This page in version {{ver.display_version}}" rel="nofollow">{{ver.display_version}}</a>
 	{%endif%}
 {%endfor%}
 {%endif%}
@@ -77,7 +77,7 @@ This page in other versions:
 	{%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}}" rel="nofollow">{{ver.display_version}}</a>
+	<a href="/docs/{{ver.display_version}}/static/{{ver.file}}" title="This page in version {{ver.display_version}}" rel="nofollow">{{ver.display_version}}</a>
 	{%endif%}
 {%endfor%}
 {%endif%}
@@ -89,38 +89,15 @@ This page in other versions:
 </div>
 
 <div id="docComments">
-{%for comment in comments%}
-{%if forloop.first%}<h2>Comments</h2>{%endif%}
-<br />
-<div class="txtCommentsWrap">
-<div class="txtCommentsContent">
-<div class="txtCommentsPoster">{{comment.poster}}</div>
-<div class="txtCommentsDate">{{comment.posted_at}}</div>
-<br style="clear: both;" />
-</div>
-<div class="txtCommentsComment">{{comment.comment|linebreaks}}</div>
-</div>
-{%endfor%}
 
-{%if can_comment%}
-<h2>Add Comment</h2>
+<h2>Submit correction</h2>
 <p>
-Please use this form to add your own comments regarding your experience with
-particular features of PostgreSQL, clarifications of the documentation, or
-hints for other users. Please note, this is <strong>not</strong> a support
-forum, and your IP address will be logged. If you have a question or need help,
-please see the <a href="/docs/faq/">faq</a>, try a
-<a href="/community/lists/">mailing list</a>, or join
-us on <a href="/community/irc">IRC</a>.
-Note that submissions containing URLs or other keywords commonly found in
-'spam' comments may be silently discarded. Please contact the
-<a href="mailto:webmaster@postgresql.org">webmaster</a> if you think this
-is happening to you in error.
+If you see anything in the documentation that is not correct, does not match
+your experience with the particular feature or requires further clarification,
+please use
+<a href="/account/comments/new/{{page.version.tree}}/{{page.file}}/" rel="nofollow">this form</a>
+to report a documentation issue.
 </p>
-<p>
-Proceed to the <a href="/account/comments/new/{{page.version.tree}}/{{page.file}}/" rel="nofollow">comment form</a>.
-</p>
-{%endif%}
 </div>
 
 <div id="docFooter">

templates/docs/index.html

@@ -21,9 +21,11 @@ written about PostgreSQL (some of which are available in their entirety online).
   <dl>
     <dt>Online Manuals</dt>
     <dd>
+      <ul>
 {%for v in versions%}
-        <p><b>{{v.treestring}}</b> ({%if not v.testing%}<a href="/docs/{{v.tree}}/interactive/index.html">with</a>/{%endif%}<a href="/docs/{{v.tree}}/static/index.html">without</a> comments)</p>
+        <li><a href="/docs/{{v.tree}}/static/index.html">{{v.treestring}}</a></li>
 {%endfor%}
+      </ul>
     </dd>
     <dt>Translated Manuals</dt>
     <dd>

templates/docs/manuals.html

@@ -8,17 +8,14 @@
 <div class="tblBasic">
 <table border="0" cellpadding="0" cellspacing="0" class="tblBasicGrey">
 <tr>
-	<th class="colFirst">Release</th>
 	<th class="colMid">Online Version</th>
 	<th class="colLast">PDF Version</th>
 </tr>
 {%for v in versions%}
 <tr{%if forloop.last%} class="lastrow"{%endif%}>
-    <td class="colFirst">{{v.treestring}}</td>
     <td class="colMid">
           <ul>
-              {%if not v.testing%}<li><a href="/docs/{{v.tree}}/interactive/index.html">With user comments</a></li>{% endif %}
-	      <li><a href="/docs/{{v.tree}}/static/index.html">Without user comments</a></li>
+            <li><a href="/docs/{{v.tree}}/static/index.html">{{v.treestring}}</a></li>
 	  </ul>
     </td>
     <td class="colLast">