def _rearrange_section(self, section: Section) -> Section:
section.children = self._rearrange_list_of_navigation_items(
section.children, )
index_page = find_index_page_in_section(section)
if index_page is None:
section.position = PAGE_DEFAULT_POSITION
else:
section.position = index_page.position
if index_page.title:
section.title = index_page.title
return section
def test_multiple_children(self):
section = Section("Parent",
[Section("Child 1", []),
Section("Child 2", [])])
self.assertEqual(AwesomeNavigation._collapse(section, None, False),
section)
self.assertEqual(AwesomeNavigation._collapse(section, None, True),
section)
self.assertEqual(AwesomeNavigation._collapse(section, False, False),
section)
self.assertEqual(AwesomeNavigation._collapse(section, True, False),
section)
self.assertEqual(AwesomeNavigation._collapse(section, True, True),
section)
self.assertEqual(AwesomeNavigation._collapse(section, False, True),
section)
def _process_section(self, section: Section,
collapse_recursive: bool) -> NavigationItem:
meta = self.meta.sections[section]
if meta.collapse_single_pages is not None:
collapse_recursive = meta.collapse_single_pages
self._set_title(section, meta)
section.children = self._process_children(section.children,
collapse_recursive, meta)
return self._collapse(section, meta.collapse, collapse_recursive)
def _generate_rest_blocks(self, items: List[NavigationItem], exclude_files: List[File]) -> Dict[str, List[NavigationItem]]:
result = {rest_item: [] for rest_item in self.rest_items}
for item in items[:]: # loop over a shallow copy of items so removing items doesn't break iteration
if isinstance(item, Page):
if item.file not in exclude_files:
for rest_item in self.rest_items:
if rest_item.matches(item.file.src_path):
items.remove(item)
result[rest_item].append(item)
break
if isinstance(item, Section):
child_result = self._generate_rest_blocks(item.children, exclude_files)
for rest_item, children in child_result.items():
if children:
result[rest_item].append(Section(item.title, children))
return result
def section(self,
title: str,
items: List[Union[NavigationItem, Meta]],
path: Optional[str] = None) -> Section:
children = []
if path is not None:
path = os.path.join(path, '.pages')
meta = Meta(path=path)
for item in items:
if isinstance(item, Meta):
meta = item
else:
children.append(item)
section = Section(title, children)
self.meta_mock.sections[section] = meta
return section
def _process_section(self, section: Section, options: Options) -> Optional[NavigationItem]:
meta = self.meta.sections[section]
collapse_recursive = options.collapse_single_pages
if meta.hide is True:
return None
if meta.collapse_single_pages is not None:
collapse_recursive = meta.collapse_single_pages
self._set_title(section, meta)
section.children = self._process_children(section.children, options, meta)
if not section.children:
return None
return self._collapse(section, meta.collapse, collapse_recursive)
def _set_title(section: Section, meta: Meta):
if meta.title is not None:
section.title = meta.title
def on_nav(self, nav, config, files):
"""
From MkDocs documentation:
==========================
The nav event is called after the site navigation is created and can
be used to alter the site navigation.
Args:
nav: Our navbar
config: Global configuration
files: List of files
Returns:
A modified navbar
"""
# Our plugin code starts here!
# We are starting by reading the configuration parameters
# for our plugin
# How many articles do we have to display in the blog part.
# This number will be doubled by the nested "previous articles"
# section
articles = self.config["articles"]
# The title of the section that will contain the blog part
# By default, it searches for a section titled "blog"
blog_section = self.config["folder"]
# Searches for a section that is titled the blog section
blogs_found = [(i, e) for i, e in enumerate(nav.items)
if e.title and e.title.lower() == blog_section.lower()]
# Have we founded that?
if not blogs_found:
# Nope. We'll give back control to MkDocs...
return nav
# Yes, since we are still here we did found at least one blog folder.
# We'll just need to pick up the first occurrence found
blog_position, blog = blogs_found[0]
# Now it's time to empty whatever that section was containing
blog.children = []
# If the number of articles that we are going to display will be
# too high, we'll also need a section in which we could place the
# exceeding articles
more = Section(title="", children=[])
# All right, it's time to start searching our mkdocs repository for
# potentials blog articles. We want to sort our list of pages by
# their URL value, in descending order.
# Why? Because each of our blog articles will be saved in this
# format:
#
# mkdocs/docs/blog/2020/01/2020-01-20--first_post.md
# mkdocs/docs/blog/2020/01/2020-01-25--second_post.md
# mkdocs/docs/blog/2020/02/2020-02-01--third_post.md
#
# By reversing the alphabetical order, We'll ensure to get this
# articles list in this order:
#
# "third post" (2020-02-01--third_post.md)
# "second post" (2020-01-25--second_post.md)
# "first post" (2020-01-20--first_post.md)
#
for page in sorted(nav.pages,
key=lambda x: x.url, reverse=True):
# Let's have a look at the URL of this page... hmm...
# Is it nested in the folder/section we have chosen for keeping
# our blog articles ? Let's have a case-insensitive check...
if blog_section + "/" in page.url.lower():
# Yes, it is in the right folder / section.
# Now, let's check if we already have enough articles in
# our blog section
if len(blog.children) < articles:
# No, there's still space available.
# Let's add this page to our blog section
blog.children.append(page)
else:
# Our blog section is already at full capacity.
# Well, let's see if we can add this article to the
# "previous articles" section that (maybe) will be
# added at the end
# Is the "More articles" section empty ?
if len(more.children) == 0:
subsection = Section(title="", children=[])
more.children.append(subsection)
else:
# Or the default subsection is already full ?
# noinspection PyUnboundLocalVariable
if len(subsection.children) >= articles:
# Yes. Add a new subsection inside of it
subsection = Section(title="", children=[])
more.children.append(subsection)
subsection.children.append(page)
# All right, we just finished scanning our MkDocs repository for
# articles. Let's add some minor finishing touches to our sections.
# Did the user allows to show this section?
if self.config["display-more-articles"]:
# How many articles do we have stored in the "More articles"
# section?
articles_count = sum([len(sub.children)
for sub in more.children])
if articles_count > 0:
# We will change the title of each subsection to display
# something like "Page 1 of X"
last_page = len(more.children)
for actual_page, subpage in enumerate(more.children,
start=1):
subpage.title = self.config["pagination"]\
.replace("%", str(actual_page), 1)\
.replace("%", str(last_page), 1)
# Last thing before adding this section to our blog...
# We need to change our "More article" section title
# accordingly to what our user has chosen
more.title = self.config["more-articles"]\
.replace("%", str(articles_count))
# Finished. Let's add our "More articles" section to our
# Blog section.
blog.children.append(more)
# THE FOLLOWING 3 LINES OF CODE ARE JUST MEANT FOR DEBUGGING PURPOSES
# ===================================================================
# import pydevd_pycharm
# pydevd_pycharm.settrace('localhost', port=5000, stdoutToServer=True,
# stderrToServer=True)
# Search for the blog section in the nav, and move it to the bottom
# Let's start by removing the blog section from wherever MkDocs has
# put it, in first place
del(nav.items[blog_position])
# Now we'll append the blog section at the end of the nav element
nav.items.append(blog)
# All finished. We can give back our modified nav to MkDocs and enjoy
# our new blog section!
return nav
def setUp(self):
self.section = Section("Section", [])
def setUp(self):
self.child = Section("Child", [])
self.parent = Section("Parent", [self.child])
def setUp(self):
self.section = Section('Section', [])
def setUp(self):
self.child = Section('Child', [])
self.parent = Section('Parent', [self.child])
