Repository: getpelican/pelican

Issue:
Multiple reST headers yields "could not find information about 'date'"
When defining posts using ReStructuredText, if one specified more than one chapter header, pelican issues the error:

```
ERROR: Skipping meta/pelican-fail.rst: could not find information about 'date'
```

This error message is particularly opaque when trying to diagnose and repair the underlying issue.

For further testing / validation, here is a failing and succeeding test case that issue the above error (or not):

# Fail

```restructuredtext
Title Line
==========

:slug: pelican-fail
:date: 2018-01-01 12:13:14+00:00
:tags: meta
:category: meta

Test file

Section Header
==============

Content
```

# Succeed

```restructuredtext
Title Line
==========

:slug: pelican-succeed
:date: 2018-01-01 12:13:14+00:00
:tags: meta
:category: meta

Test file

Section Header
--------------

Content
```

The notable difference is the character used to underline "Section Header"


Discussion:
This seems to duplicate the closed #1231 but is definitely still present in pelican 3.7.1
That is a peculiarity of reStructuredText. "Document Title" is a lone top-level section and metadata ([bibliographic field](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bibliographic-fields) in rst doc) need to follow this right after. If you have multiple top-level headers then this structure won't hold and intended metadata is treated as part of the regular content instead.

There is not much pelican do at this point. That's what the rst parser passes.
I recognize the underlying cause is a matter of reStructuredText's behavior and I don't think it's on pelican to fix the problem.

However, it would good if pelican issued a more informative error message that pointed the user in the direction of fixing the problem. Personally, I spent quite a while monkeying with dates and date configurations until I happened to find the problem entirely by coincidence.
That's understandable but detecting this from pelican side isn't the most trivial task.
Hi George. When feasible, helpful error messages are indeed better than less-than-helpful error messages. Would you be interested in helping contribute a solution so that Pelican emits a more helpful error message for this particular case?


Resolving patch:
diff --git a/pelican/readers.py b/pelican/readers.py
--- a/pelican/readers.py
+++ b/pelican/readers.py
@@ -203,11 +203,18 @@ def __init__(self, *args, **kwargs):
     def __init__(self, *args, **kwargs):
         super(RstReader, self).__init__(*args, **kwargs)
 
-    def _parse_metadata(self, document):
+    def _parse_metadata(self, document, source_path):
         """Return the dict containing document metadata"""
         formatted_fields = self.settings['FORMATTED_FIELDS']
 
         output = {}
+
+        if document.first_child_matching_class(docutils.nodes.title) is None:
+            logger.warning(
+                'Document title missing in file %s: '
+                'Ensure exactly one top level section',
+                source_path)
+
         for docinfo in document.traverse(docutils.nodes.docinfo):
             for element in docinfo.children:
                 if element.tagname == 'field':  # custom fields (e.g. summary)
@@ -257,7 +264,7 @@ def read(self, source_path):
         parts = pub.writer.parts
         content = parts.get('body')
 
-        metadata = self._parse_metadata(pub.document)
+        metadata = self._parse_metadata(pub.document, source_path)
         metadata.setdefault('title', parts.get('title'))
 
         return content, metadata


Test patch: