Better than nothing

docs/tools/single_page.py

@@ -24,55 +24,71 @@ def recursive_values(item):
         yield item
 
 
+anchor_not_allowed_chars = re.compile(r'[^\w\-]')
+def generate_anchor_from_path(path):
+    return re.sub(anchor_not_allowed_chars, '-', path)
+
+
+def replace_link(match, path):
+    link = match.group(1)
+    if link.endswith('/'):
+        link = link[0:-1] + '.md'
+
+    return '(#{})'.format(generate_anchor_from_path(os.path.normpath(os.path.join(os.path.dirname(path), link))))
+
+
+# Concatenates Markdown files to a single file.
 def concatenate(lang, docs_path, single_page_file, nav):
     lang_path = os.path.join(docs_path, lang)
-    az_re = re.compile(r'[a-z]')
 
     proj_config = f'{docs_path}/toc_{lang}.yml'
     if os.path.exists(proj_config):
         with open(proj_config) as cfg_file:
             nav = yaml.full_load(cfg_file.read())['nav']
+
     files_to_concatenate = list(recursive_values(nav))
     files_count = len(files_to_concatenate)
     logging.info(f'{files_count} files will be concatenated into single md-file for {lang}.')
     logging.debug('Concatenating: ' + ', '.join(files_to_concatenate))
     assert files_count > 0, f'Empty single-page for {lang}'
 
+    # (../anything) or (../anything#anchor) or (xyz-abc.md) or (xyz-abc.md#anchor)
+    relative_link_regexp = re.compile(r'\((\.\./[^)#]+|[\w\-]+\.md)(?:#[^\)]*)?\)')
+
     for path in files_to_concatenate:
-        if path.endswith('introduction/info.md'):
-            continue
         try:
             with open(os.path.join(lang_path, path)) as f:
-                anchors = set()
-                tmp_path = path.replace('/index.md', '/').replace('.md', '/')
-                prefixes = ['', '../', '../../', '../../../']
-                parts = tmp_path.split('/')
-                anchors.add(parts[-2] + '/')
-                anchors.add('/'.join(parts[1:]))
-
-                for part in parts[0:-2] if len(parts) > 2 else parts:
-                    for prefix in prefixes:
-                        anchor = prefix + tmp_path
-                        if anchor:
-                            anchors.add(anchor)
-                            anchors.add('../' + anchor)
-                            anchors.add('../../' + anchor)
-                    tmp_path = tmp_path.replace(part, '..')
-
-                for anchor in anchors:
-                    if re.search(az_re, anchor):
-                        single_page_file.write('<a name="%s"></a>' % anchor)
-
-                single_page_file.write('\n')
+                # Insert a horizontal ruler. Then insert an anchor that we will link to. Its name will be a path to the .md file.
+                single_page_file.write('\n______\n<a name="%s"></a>\n' % generate_anchor_from_path(path))
 
                 in_metadata = False
-                for l in f:
-                    if l.startswith('---'):
+                for line in f:
+                    # Skip YAML metadata.
+                    if line == '---\n':
                         in_metadata = not in_metadata
-                    if l.startswith('#'):
-                        l = '#' + l
+                        continue
+
                     if not in_metadata:
-                        single_page_file.write(l)
+                        # Increase the level of headers.
+                        if line.startswith('#'):
+                            line = '#' + line
+
+                        # Replace links within the docs.
+
+                        if re.search(relative_link_regexp, line):
+                            line = re.sub(
+                                relative_link_regexp,
+                                lambda match: replace_link(match, path),
+                                line)
+
+                            # If failed to replace the relative link, print to log
+                            if '../' in line:
+                                logging.info('Failed to resolve relative link:')
+                                logging.info(path)
+                                logging.info(line)
+
+                        single_page_file.write(line)
+
         except IOError as e:
             logging.warning(str(e))
 
@@ -86,7 +102,7 @@ def build_single_page_version(lang, args, nav, cfg):
     extra['single_page'] = True
     extra['is_amp'] = False
 
-    with util.autoremoved_file(os.path.join(args.docs_dir, lang, 'single.md')) as single_md:
+    with open(os.path.join(args.docs_dir, lang, 'single.md'), 'w') as single_md:
         concatenate(lang, args.docs_dir, single_md, nav)
 
         with util.temp_dir() as site_temp:
@@ -123,11 +139,14 @@ def build_single_page_version(lang, args, nav, cfg):
 
                     single_page_index_html = os.path.join(single_page_output_path, 'index.html')
                     single_page_content_js = os.path.join(single_page_output_path, 'content.js')
+
                     with open(single_page_index_html, 'r') as f:
                         sp_prefix, sp_js, sp_suffix = f.read().split('<!-- BREAK -->')
+
                     with open(single_page_index_html, 'w') as f:
                         f.write(sp_prefix)
                         f.write(sp_suffix)
+
                     with open(single_page_content_js, 'w') as f:
                         if args.minify:
                             import jsmin
@@ -151,6 +170,7 @@ def build_single_page_version(lang, args, nav, cfg):
                     js_in = ' '.join(website.get_js_in(args))
                     subprocess.check_call(f'cat {css_in} > {test_dir}/css/base.css', shell=True)
                     subprocess.check_call(f'cat {js_in} > {test_dir}/js/base.js', shell=True)
+
                     if args.save_raw_single_page:
                         shutil.copytree(test_dir, args.save_raw_single_page)
 

docs/tools/util.py

@@ -22,15 +22,6 @@ def temp_dir():
         shutil.rmtree(path)
 
 
-@contextlib.contextmanager
-def autoremoved_file(path):
-    try:
-        with open(path, 'w') as handle:
-            yield handle
-    finally:
-        os.unlink(path)
-
-
 @contextlib.contextmanager
 def cd(new_cwd):
     old_cwd = os.getcwd()