Skip to content

Commit

Permalink
Better docstrings for path handlers
Browse files Browse the repository at this point in the history
  • Loading branch information
@ralsina
ralsina committed Sep 4, 2015
1 parent 2bd9ea5 commit 7638f48
Show file tree
Hide file tree
Showing 7 changed files with 101 additions and 23 deletions.
10 changes: 8 additions & 2 deletions nikola/plugins/task/archive.py
View file
Expand Up @@ -223,7 +223,10 @@ def gen_tasks(self):
yield self._prepare_task(kw, None, lang, None, items, "list.tmpl", kw["messages"][lang]["Archive"])

def archive_path(self, name, lang, is_feed=False):
"""Return archive paths."""
"""Link to archive path, name is the year. For example:
link://archive/2013 => /archives/2013/index.html
"""
if is_feed:
extension = ".atom"
archive_file = os.path.splitext(self.site.config['ARCHIVE_FILENAME'])[0] + extension
Expand All @@ -241,5 +244,8 @@ def archive_path(self, name, lang, is_feed=False):
archive_file] if _f]

def archive_atom_path(self, name, lang):
"""Return Atom archive paths."""
"""Link to atom archive path, name is the year. For example:
link://archive_atom/2013 => /archives/2013/index.atom
"""
return self.archive_path(name, lang, is_feed=True)
20 changes: 16 additions & 4 deletions nikola/plugins/task/authors.py
View file
Expand Up @@ -252,13 +252,19 @@ def slugify_author_name(self, name):
return name

def author_index_path(self, name, lang):
"""Return path to the author index."""
"""Link to the author's index. For example:
link://authors/ => /authors/index.html
"""
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['AUTHOR_PATH'],
self.site.config['INDEX_FILE']] if _f]

def author_path(self, name, lang):
"""Return path to an author."""
"""Link to an author's page. For example:
link://author/joe => /authors/joe.html
"""
if self.site.config['PRETTY_URLS']:
return [_f for _f in [
self.site.config['TRANSLATIONS'][lang],
Expand All @@ -272,13 +278,19 @@ def author_path(self, name, lang):
self.slugify_author_name(name) + ".html"] if _f]

def author_atom_path(self, name, lang):
"""Return path to an author Atom feed."""
"""Link to an author's Atom feed. For example:
link://author_atom/joe => /authors/joe.atom
"""
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['AUTHOR_PATH'], self.slugify_author_name(name) + ".atom"] if
_f]

def author_rss_path(self, name, lang):
"""Return path to an author RSS feed."""
"""Link to an author's RSS feed. For example::
link://author_rss/joe => /authors/joe.rss
"""
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['AUTHOR_PATH'], self.slugify_author_name(name) + ".xml"] if
_f]
Expand Down
22 changes: 19 additions & 3 deletions nikola/plugins/task/galleries.py
View file
Expand Up @@ -122,20 +122,36 @@ def _find_gallery_path(self, name):
sys.exit(1)

def gallery_path(self, name, lang):
"""Return a gallery path."""
"""Link to an image gallery's path.
It will try to find a gallery with that name if it's not ambiguous
or with that path. For example:
link://gallery/london => /galleries/trips/london/index.html
link://gallery/trips/london => /galleries/trips/london/index.html
"""
gallery_path = self._find_gallery_path(name)
return [_f for _f in [self.site.config['TRANSLATIONS'][lang]] +
gallery_path.split(os.sep) +
[self.site.config['INDEX_FILE']] if _f]

def gallery_global_path(self, name, lang):
"""Return the global gallery path, which contains images."""
"""Link to the global gallery path, which contains all the images."""
gallery_path = self._find_gallery_path(name)
return [_f for _f in gallery_path.split(os.sep) +
[self.site.config['INDEX_FILE']] if _f]

def gallery_rss_path(self, name, lang):
"""Return path to the RSS file for a gallery."""
"""Link to an image gallery's RSS feed.
It will try to find a gallery with that name if it's not ambiguous
or with that path. For example:
link://gallery_rss/london => /galleries/trips/london/rss.xml
link://gallery_rss/trips/london => /galleries/trips/london/rss.xml
"""
gallery_path = self._find_gallery_path(name)
return [_f for _f in [self.site.config['TRANSLATIONS'][lang]] +
gallery_path.split(os.sep) +
Expand Down
20 changes: 16 additions & 4 deletions nikola/plugins/task/indexes.py
View file
Expand Up @@ -217,7 +217,10 @@ def cat_path(i, displayed_i, num_pages, force_addition, extension=None):
yield task

def index_path(self, name, lang, is_feed=False):
"""Return path to an index."""
"""Link to a numbered index. For example:
link://index/3 => /index-3.html
"""
extension = None
if is_feed:
extension = ".atom"
Expand All @@ -234,7 +237,10 @@ def index_path(self, name, lang, is_feed=False):
extension=extension)

def index_section_path(self, name, lang, is_feed=False):
"""Return path to an index for sections."""
"""Link to the index for a section. For example:
link://section_index/cars => /cars/index.html
"""
extension = None

if is_feed:
Expand All @@ -252,9 +258,15 @@ def index_section_path(self, name, lang, is_feed=False):
extension=extension)

def index_atom_path(self, name, lang):
"""Return path to an Atom index."""
"""Link to a numbered Atom index. For example:
link://index_atom/3 => /index-3.atom
"""
return self.index_path(name, lang, is_feed=True)

def index_section_atom_path(self, name, lang):
"""Return path to an Atom index for sections."""
"""Link to the Atom index for a section. For example:
link://section_index_atom/cars => /cars/index.atom
"""
return self.index_section_path(name, lang, is_feed=True)
7 changes: 6 additions & 1 deletion nikola/plugins/task/listings.py
View file
Expand Up @@ -255,7 +255,12 @@ def render_listing(in_name, out_name, input_folder, output_folder, folders=[], f
}, self.kw["filters"])

def listing_path(self, namep, lang):
"""Return path to a listing."""
"""A link to a listing. It will try to use the file name if
it's not ambiguous, or the file path. For example:
link://listing/hello.py => /listings/tutorial/hello.py.html
link://listing/tutorial/hello.py => /listings/tutorial/hello.py.html
"""
namep = namep.replace('/', os.sep)
nameh = namep + '.html'
for name in (namep, nameh):
Expand Down
5 changes: 4 additions & 1 deletion nikola/plugins/task/rss.py
View file
Expand Up @@ -106,6 +106,9 @@ def gen_tasks(self):
yield utils.apply_filters(task, kw['filters'])

def rss_path(self, name, lang):
"""Return RSS path."""
"""A link to the RSS feed path. For example:
link://rss => /blog/rss.xml
"""
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['RSS_PATH'], 'rss.xml'] if _f]
40 changes: 32 additions & 8 deletions nikola/plugins/task/tags.py
View file
Expand Up @@ -394,19 +394,28 @@ def slugify_tag_name(self, name):
return name

def tag_index_path(self, name, lang):
"""Return path to the tag index."""
"""A link to the tag index. For example:
link://tag_index => /tags/index.html
"""
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['TAG_PATH'],
self.site.config['INDEX_FILE']] if _f]

def category_index_path(self, name, lang):
"""Return path to the category index."""
"""A link to the category index. For example:
link://category_index => /categories/index.html
"""
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['CATEGORY_PATH'],
self.site.config['INDEX_FILE']] if _f]

def tag_path(self, name, lang):
"""Return path to a tag."""
"""A link to a tag's page. For example:
link://tag/cats => /tags/cats.html
"""
if self.site.config['PRETTY_URLS']:
return [_f for _f in [
self.site.config['TRANSLATIONS'][lang],
Expand All @@ -420,13 +429,19 @@ def tag_path(self, name, lang):
self.slugify_tag_name(name) + ".html"] if _f]

def tag_atom_path(self, name, lang):
"""Return path to a tag Atom feed."""
"""A link to a tag's Atom feed. For example:
link://tag_atom/cats => /tags/cats.atom
"""
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['TAG_PATH'], self.slugify_tag_name(name) + ".atom"] if
_f]

def tag_rss_path(self, name, lang):
"""Return path to a tag RSS feed."""
"""A link to a tag's RSS feed. For example:
link://tag_rss/cats => /tags/cats.xml
"""
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['TAG_PATH'], self.slugify_tag_name(name) + ".xml"] if
_f]
Expand All @@ -447,7 +462,10 @@ def _add_extension(self, path, extension):
return path

def category_path(self, name, lang):
"""Return path to a category."""
"""A link to a category. For example:
link://category/dogs => /categories/dogs.html
"""
if self.site.config['PRETTY_URLS']:
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['CATEGORY_PATH']] if
Expand All @@ -458,13 +476,19 @@ def category_path(self, name, lang):
_f] + self._add_extension(self.slugify_category_name(name), ".html")

def category_atom_path(self, name, lang):
"""Return path to a category Atom feed."""
"""A link to a category's Atom feed. For example:
link://category_atom/dogs => /categories/dogs.atom
"""
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['CATEGORY_PATH']] if
_f] + self._add_extension(self.slugify_category_name(name), ".atom")

def category_rss_path(self, name, lang):
"""Return path to a category RSS feed."""
"""A link to a category's RSS feed. For example:
link://category_rss/dogs => /categories/dogs.xml
"""
return [_f for _f in [self.site.config['TRANSLATIONS'][lang],
self.site.config['CATEGORY_PATH']] if
_f] + self._add_extension(self.slugify_category_name(name), ".xml")

0 comments on commit 7638f48

Please sign in to comment.