Update the specification of "documentation_of" string

-   Making the document clear and encourage to use `./` or `..` for relative paths and `//` for absolute paths.
-   In UNIX, traditionally, a path begins with two successive slashes is interpreted in an implementation-defined manner.
-   This doesn't break existing documents in almost cases. It has a conservative fallback mechanism.

Author: kmyk

.verify-helper/docs/static/document.ja.md

@@ -101,19 +101,22 @@ list_dependencies = "sed 's/^@include \"\\(.*\\)\"$/\\1/ ; t ; d' {path}"
 [Front Matter](http://jekyllrb-ja.github.io/docs/front-matter/) 形式で `documentation_of` という項目にファイルを指定しておくと、指定したファイルについての生成されたドキュメント中に、Markdown ファイルの中身が挿入されます。
 
 たとえば、`path/to/segment_tree.hpp` というファイルに説明を Markdown で追加したいときは `for/bar.md` などに次のように書きます。
-[Front Matter](https://jekyllrb.com/docs/front-matter/)
 
 ```
 ---
 title: Segment Tree
-documentation_of: path/to/segment_tree.hpp
+documentation_of: ./path/to/segment_tree.hpp
 ---
 
 ## 説明
 
 このファイルでは、……
 ```
 
+`documentation_of` 文字列は、`./` あるいは `..` から始まる場合は Markdown ファイルのパスからの相対パスであると認識されます。また、`//` から初まる場合は `.verify-helper` ディレクトリがある場所をルートとする絶対パスであると認識されます。
+また、ディレクトリ区切り文字には `/` を使い、大文字小文字を正しく入力してください。
+
+
 ### トップページへの Markdown の埋め込み
 
 `.verify-helper/docs/index.md` というファイルを作って、そこに Markdown で書いてください。

.verify-helper/docs/static/document.md

@@ -104,14 +104,19 @@ For example, to add description to a document of a file `path/to/segment_tree.hp
 ```
 ---
 title: Segment Tree
-documentation_of: path/to/segment_tree.hpp
+documentation_of: ./path/to/segment_tree.hpp
 ---
 
 ## Description
 
 In this file, ...
 ```
 
+The `documentation_of` string is recognized as a relative path from the Markdown file when the string starts with `./` or `..`.
+The `documentation_of` string is recognized as a absolute path from the directory which has `.verify-helper` directory as the root when the string starts with `//`.
+The path should use `/` as directory separator be case-sensitive.
+
+
 
 ### Embedding Markdown to the top page
 

onlinejudge_verify/documentation/configure.py

@@ -212,6 +212,32 @@ def apply_exclude_list_to_stats(*, excluded_paths: List[pathlib.Path], source_co
     return result
 
 
+def resolve_documentation_of(documentation_of: str, *, markdown_path: pathlib.Path, basedir: pathlib.Path) -> Optional[pathlib.Path]:
+    if documentation_of.startswith('.'):
+        # a relative path
+        path = markdown_path.parent / pathlib.PosixPath(documentation_of)
+        if path.exists() and basedir in path.resolve().parents:
+            return path
+    elif documentation_of.startswith('//'):
+        # from the document root
+        path = basedir / pathlib.PosixPath(documentation_of[2:])
+        if path.exists() and basedir in path.resolve().parents:
+            return path
+
+    # guessing
+    logger.warning('No file at the expected path from the `documentation_of` path. The `documentation_of` path should use `/` for path separator, and start with `.` for a relative path from the path of the Markdown file, or start with `//` for a absolute path from the root of the repository.: %s', documentation_of)
+    candidate_paths = [
+        basedir / pathlib.PosixPath(documentation_of),
+        basedir / pathlib.Path(documentation_of),
+        markdown_path.parent / pathlib.PosixPath(documentation_of),
+        markdown_path.parent / pathlib.Path(documentation_of),
+    ]
+    for path in candidate_paths:
+        if path.exists() and basedir in path.resolve().parents:
+            return path
+    return None
+
+
 def convert_to_page_render_jobs(*, source_code_stats: List[SourceCodeStat], markdown_paths: List[pathlib.Path], site_render_config: SiteRenderConfig) -> List[PageRenderJob]:
     basedir = site_render_config.basedir
 
@@ -230,11 +256,14 @@ def convert_to_page_render_jobs(*, source_code_stats: List[SourceCodeStat], mark
         path = markdown_relative_path
         documentation_of = front_matter.get(FrontMatterItem.documentation_of.value)
         if documentation_of is not None:
-            if not (basedir / pathlib.Path(documentation_of)).exists():
+            documentation_of_path = resolve_documentation_of(documentation_of, markdown_path=path, basedir=basedir)
+            if documentation_of_path is None:
                 logger.warning('the `documentation_of` path of %s is not found: %s', str(path), documentation_of)
+                del front_matter[FrontMatterItem.documentation_of.value]
                 continue
-            documentation_of_path = (basedir / pathlib.Path(documentation_of)).resolve().relative_to(basedir)
-            path = documentation_of_path.parent / (documentation_of_path.name + '.md')
+            documentation_of_relative_path = documentation_of_path.resolve().relative_to(basedir)
+            front_matter[FrontMatterItem.documentation_of.value] = str(documentation_of_relative_path)
+            path = documentation_of_relative_path.parent / (documentation_of_path.name + '.md')
 
         job = PageRenderJob(
             path=path,

tests/test_docs.py

@@ -1,13 +1,78 @@
 """This module has tests for the docs subcommand.
 """
 
+import pathlib
+import random
+import textwrap
 import unittest
+from typing import *
 
 import onlinejudge_verify.main
+import tests.utils as utils
 
 
 class TestDocsSubcommandSmoke(unittest.TestCase):
-    """TestDocsSubcommandSmoke is a smoke tests of `docs` subcommand.
+    """TestDocsSubcommandSmoke is a class for smoke tests of `docs` subcommand.
     """
     def test_run(self) -> None:
         onlinejudge_verify.main.subcommand_docs()
+
+
+class TestDocsSubcommand(unittest.TestCase):
+    """TestDocsSubcommand is a class for end-to-end tests of `docs` subcommand.
+    """
+    def test_documentation_of(self) -> None:
+        get_random_string = lambda: ''.join([random.choice('0123456789abcdef') for _ in range(64)])
+        random_relative_hpp = get_random_string()
+        random_absolute_hpp = get_random_string()
+        random_no_document_hpp = get_random_string()
+        random_relative_md = get_random_string()
+        random_absolute_md = get_random_string()
+        random_standalone_page_md = get_random_string()
+
+        files = {
+            pathlib.Path('src', 'a', 'b', 'relative.hpp'): random_relative_hpp.encode(),
+            pathlib.Path('src', 'a', 'b', 'absolute.hpp'): random_absolute_hpp.encode(),
+            pathlib.Path('src', 'a', 'b', 'no-document.hpp'): random_no_document_hpp.encode(),
+            pathlib.Path('docs', 'x', 'y', 'relative.md'): textwrap.dedent(f"""\
+                ---
+                title: relative.md
+                documentation_of: ../../../src/a/b/relative.hpp
+                ---
+
+                {random_relative_md}
+                """).encode(),
+            pathlib.Path('docs', 'x', 'y', 'absolute.md'): textwrap.dedent(f"""\
+                ---
+                title: absolute.md
+                documentation_of: //src/a/b/absolute.hpp
+                ---
+
+                {random_absolute_md}
+                """).encode(),
+            pathlib.Path('docs', 'x', 'y', 'standalone-page.md'): textwrap.dedent(f"""\
+                ---
+                title: standalone page
+                ---
+
+                {random_standalone_page_md}
+                """).encode(),
+        }
+
+        destination_dir = pathlib.Path('.verify-helper', 'markdown')
+        expected: Dict[pathlib.Path, List[str]] = {
+            destination_dir / 'src' / 'a' / 'b' / 'relative.hpp.md': [random_relative_hpp, random_relative_md],
+            destination_dir / 'src' / 'a' / 'b' / 'absolute.hpp.md': [random_absolute_hpp, random_absolute_md],
+            destination_dir / 'src' / 'a' / 'b' / 'no-document.hpp.md': [random_no_document_hpp],
+            destination_dir / 'docs' / 'x' / 'y' / 'standalone-page.md': [random_standalone_page_md],
+        }
+
+        with utils.load_files_pathlib(files) as tempdir:
+            with utils.chdir(tempdir):
+                onlinejudge_verify.main.subcommand_docs()
+                for path, keywords in expected.items():
+                    self.assertTrue((tempdir / path).exists())
+                    with open(tempdir / path) as fh:
+                        content = fh.read()
+                    for keyword in keywords:
+                        self.assertIn(keyword, content)