Allow to build a list of pages in the given languages

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## master (unreleased)
 
 * typo fix in the french text ("exemple" instead of "example").
+* Allow to build extra pages ; the `meta.yaml` file must now provide a list of pages to be built (#27 ; was a requirement for #24).
 
 ## 1.1.0 (2016-05-14)
 

README.md

@@ -53,17 +53,29 @@ The meta file is a [YAML](http://yaml.org/), but it shouldn't be a problem. Your
 
 ```yaml
 label: Klingon
-author: B'Elanna Torres
-version: '1.1.2'
+pages:
+    -
+        label: The Black Hack in Klingon
+        author: B'Elanna Torres
+        version: '1.1.2'
+    -
+        label: Additional Things
+        author: B'Ellana Torres
+        filename: additional-things.md
+
 ```
 
 **Important**
 
+* The meta file is completely optional, but it'll help improve the look'n'feel of the homepage & build the extra content. If you don't have this `meta.yaml` file, the site builder will create the main page (The Black Hack rules) but it won't build the other contents. If you have difficulties creating this YAML file, don't worry, I'll take care of it.
 * All the field **names** are case-sensitive, so be careful if you're writing this file yourself.
-* The meta file is completely optional, but it'll help improve the look'n'feel of the homepage.
-* None of the fields are required you can only specify one, two or all of them ; your choice.
 * even though the `author` information is optional, although I'd recommend to provide it, in order to receive feedback (including praises from the community).
 
+*Required fields:*
+
+* *label*: This will be displayed on the homepage, it's the language label (that is to say "Français" for "French"),
+* the *filename* field is optional if your language only has the main translation (The Black Hack ruleset) ; if you want to build extra pages (for example *Additional Things*, you **must** provide the filename).
+
 ### Specific styles
 
 **Note:** If you think that the following is too complicated for you, don't worry, I'll take care of this.

build.py

@@ -21,6 +21,7 @@
 # Serving .md files as UTF-8.
 AddType 'text/plain; charset=UTF-8' md
 """.strip()
+DEFAULT_PAGE = {}
 
 
 class Builder(object):
@@ -107,25 +108,49 @@ def get_page_title(self, directory):
             if 'label' in meta:
                 return meta.get('label', None)
 
+    def page_update(self, language, page):
+        """
+        Update the page dict, to be shared by the individual pages & homepage.
+        """
+        page['language'] = language
+        if 'filename' not in page:
+            page['filename'] = 'the-black-hack.md'
+
+        basefile, _ = os.path.splitext(page['filename'])
+        if page['filename'] == 'the-black-hack.md':
+            page['target_filename'] = 'index'
+        else:
+            page['target_filename'] = basefile
+        page['raw_filename'] = basefile
+
+    def page_build(self, directory, page):
+        "Build individual page."
+        title = self.get_page_title(directory) or directory
+        source_filepath = join(directory, page['filename'])
+        body = self.convert_md(source_filepath)
+        target_dir = join(self.build_path, directory)
+        target_filename = page['target_filename']
+        self.mkdir(target_dir)
+        target_filepath = join(target_dir, '{}.html'.format(target_filename))
+        self.write_html(
+            target_filepath,
+            body=body,
+            title=title,
+            prefix="../",
+            source_file=page['filename'],
+        )
+        # Copy source to the target_dir
+        shutil.copyfile(source_filepath, join(target_dir, page['filename']))
+
     def build_dir(self, directory):
         "Build the directory"
-        filepath = join(directory, 'the-black-hack.md')
-        if os.path.exists(filepath):
+        mandatory_file = join(directory, 'the-black-hack.md')
+        if os.path.exists(mandatory_file):
             self.languages.append(directory)
-            title = self.get_page_title(directory) or directory
-            body = self.convert_md(filepath)
-            target_dir = join(self.build_path, directory)
-            self.mkdir(target_dir)
-            target_filepath = join(target_dir, 'index.html')
-            self.write_html(
-                target_filepath,
-                body=body,
-                title=title,
-                prefix="../",
-                source_file='the-black-hack.md',
-            )
-            # Copy source to the target_dir
-            shutil.copyfile(filepath, join(target_dir, 'the-black-hack.md'))
+            meta_language = self.meta.get(directory, {})
+            for page in meta_language.get('pages', [DEFAULT_PAGE]):
+                self.page_update(directory, page)
+                self.page_build(directory, page)
 
     def update_meta(self, directory):
         "Update meta information dictionary"
@@ -136,39 +161,50 @@ def update_meta(self, directory):
                 content = fd.read()
             self.meta[directory] = yaml.load(content)
 
+    def get_item_homepage(self, language, page):
+        label = page.get('label', page['raw_filename'])
+        if page['target_filename'] != 'index':
+            target = '{}.html'.format(page['target_filename'])
+        else:
+            target = ''
+        item = '* [{label}]({language}/{target})'.format(
+            label=label,
+            language=language,
+            target=target,
+        )
+
+        # Add optional author
+        author = page.get('author', None)
+        if author:
+            item = '{}, by {}'.format(item, author)
+
+        # Add optional version
+        version = page.get('version', None)
+        if version:
+            item = '{} (v{})'.format(item, version)
+
+        # Add link to source
+        item = '{item} ([source]({language}/{filename}))'.format(
+            item=item,
+            language=language,
+            filename=page['filename'],
+        )
+
+        return item
+
     def build_homepage_text_list(self):
         "Build the full text list for the homepage"
         # Build text list
         text_list = []
         text_list.append('')
         for language in self.languages:
             label = language
-            author = None
-            version = None
-            if language in self.meta:
-                label = self.meta[language].get('label', label)
-                author = self.meta[language].get('author', None)
-                version = self.meta[language].get('version', None)
-            item = '* [{label}]({language}/)'.format(
-                label=label,
-                language=language
-            )
-
-            # Add optional author
-            if author:
-                item = '{}, by {}'.format(item, author)
-
-            # Add optional version
-            if version:
-                item = '{} (v{})'.format(item, version)
-
-            # Add link to source
-            item = '{item} ([source]({language}/the-black-hack.md))'.format(
-                item=item,
-                language=language,
-            )
-
-            text_list.append(item)
+            meta_language = self.meta.get(language, {})
+            label = meta_language.get('label', label)
+            text_list.append('### {}'.format(label))
+            for page in meta_language.get('pages', [DEFAULT_PAGE]):
+                item = self.get_item_homepage(language, page)
+                text_list.append(item)
 
         text_list.append('')
         return text_list

english/meta.yaml

@@ -1,3 +1,6 @@
 label: English
-author: David Black
-version: '1.2'
+pages:
+    -
+        label: The Black Hack
+        author: David Black
+        version: '1.2'

french/meta.yaml

@@ -1,3 +1,6 @@
 label: Français
-author: Bruno Bord
-version: '1.0'
+pages:
+    -
+        label: Le Black Hack
+        author: Bruno Bord
+        version: '1.0'

spanish/meta.yaml

@@ -1,3 +1,6 @@
 label: Castellano
-author: Rafael Pardo Macías
-version: '0.3'
+pages:
+    -
+        label: Le Black Hack
+        author: Rafael Pardo Macías
+        version: '0.3'