Added Testing to READMEs (#38)

* Setting up testing section

* Added requirements

* Added test data to README

* Added Glotter notes to all READMEs

* Added install requires to setup.py

* Added Testing info to READMEs

* Added requirements links

* Updated setup version

* Wrote a wild regex...

* Added future fix

* Fixed lowercase issue

Author: jrg94

generate_docs/markdown.py

@@ -1,5 +1,6 @@
 import os
 import pathlib
+import sys
 from urllib.error import HTTPError
 from urllib import request
 
@@ -46,6 +47,20 @@ def build_doc_link(sample_program: SampleProgram, text: str) -> str:
     return markdown_url
 
 
+def build_req_link(sample_program: SampleProgram) -> str:
+    """
+    A handy abstraction for the create_md_link() method which creates a link to a sample programs docs page.
+    (e.g., https://sample-programs.therenegadecoder.com/projects/even-odd/c/)
+    :param sample_program: the sample program
+    :return: a markdown link to the docs page if it exists; an empty string otherwise
+    """
+    if not verify_link(sample_program.sample_program_req_url):
+        print(f"{sample_program.file_name} is not currently supported by this repo.")
+        sys.exit(1)
+    else:
+        return f"{create_md_link('Requirements', sample_program.sample_program_req_url)}"
+
+
 def verify_link(url: str) -> bool:
     """
     Verifies that a URL is a valid URL.

generate_docs/readme.py

@@ -1,24 +1,23 @@
-from generate_docs.markdown import MarkdownPage, build_doc_link, verify_link
+from generate_docs.markdown import MarkdownPage, build_doc_link, verify_link, build_req_link
 from generate_docs.repo import Repo, LanguageCollection
 
 
 def _get_intro_text(language: LanguageCollection) -> str:
     introduction = f"Welcome to Sample Programs in {language.get_readable_name()}!"
     docs = f"""To find documentation related to the {language.get_readable_name()} 
-    code in this repo, look [here]({language.sample_program_url}).
-    """
-    interlude_valid = "Otherwise, below you'll find a list of code snippets in this collection."
-    interlude_invalid = "Below, you'll find a list of code snippets in this collection."
-    emojis = """
-    Code snippets preceded by :warning: link to a GitHub 
-    issue query featuring a possible article request issue. If an article request issue 
-    doesn't exist, we encourage you to create one. Meanwhile, code snippets preceded 
-    by :white_check_mark: link to an existing article which provides further documentation.
-    """
+code in this repo, look [here]({language.sample_program_url})."""
     if not verify_link(language.sample_program_url):
-        return " ".join([introduction, interlude_invalid, emojis])
+        return introduction
     else:
-        return " ".join([introduction, docs, interlude_valid, emojis])
+        return " ".join([introduction, docs])
+
+
+def _get_sample_programs_text() -> str:
+    return """Below, you'll find a list of code snippets in this collection.
+Code snippets preceded by :warning: link to a GitHub 
+issue query featuring a possible article request issue. If an article request issue 
+doesn't exist, we encourage you to create one. Meanwhile, code snippets preceded 
+by :white_check_mark: link to an existing article which provides further documentation."""
 
 
 def _generate_program_list(language: LanguageCollection) -> list:
@@ -31,13 +30,45 @@ def _generate_program_list(language: LanguageCollection) -> list:
     for program in language.sample_programs:
         readable_name = program.normalized_name.replace("-", " ").title()
         doc_link = build_doc_link(program, f"{readable_name} in {language.get_readable_name()}")
-        list_items.append(f"- {doc_link}")
+        req_link = build_req_link(program)
+        list_items.append(f"- {doc_link} [{req_link}]")
     return list_items
 
 
+def _generate_testing_section(language: LanguageCollection):
+    test_data = language.get_test_data()
+    if not test_data:
+        return """This language currently does not feature testing. If you'd like to help in the efforts to test all
+of the code in this repo, consider creating a testinfo.yml file with the following information:
+        
+```yml
+folder:
+  extension: 
+  naming:
+
+container:
+  image: 
+  tag: 
+  cmd:
+```
+
+See the [Glotter project](https://github.com/auroq/glotter) for more information on how to create a testinfo file. 
+"""
+    else:
+        return f"""The following list shares details about what we're using to test all Sample Programs in 
+{language.get_readable_name()}.
+        
+- Docker Image: {test_data["container"]["image"]}
+- Docker Tag: {test_data["container"]["tag"]}
+
+See the [Glotter project](https://github.com/auroq/glotter) for more information on how we handle testing. 
+"""
+
+
 def _generate_credit():
-    return """This page was generated automatically by the Sample Programs Docs Generator. 
-    Find out how to support this project [here](https://github.com/TheRenegadeCoder/sample-programs-docs-generator)."""
+    return """---
+This page was generated automatically by the Sample Programs Docs Generator. 
+Find out how to support this project [here](https://github.com/TheRenegadeCoder/sample-programs-docs-generator)."""
 
 
 class ReadMeCatalog:
@@ -61,13 +92,26 @@ def _build_readme(self, language: LanguageCollection) -> None:
         :return: None
         """
         page = MarkdownPage("README")
+
+        # Introduction
         page.add_content(f"# Sample Programs in {language.get_readable_name()}")
         page.add_section_break()
         page.add_content(_get_intro_text(language))
         page.add_section_break()
+
+        # Sample Programs List
+        page.add_content("## Sample Programs List")
+        page.add_section_break()
+        page.add_content(_get_sample_programs_text())
+        page.add_section_break()
         page.add_content(*_generate_program_list(language))
         page.add_section_break()
+
+        # Testing
+        page.add_content("## Testing")
+        page.add_content(_generate_testing_section(language))
         page.add_content(_generate_credit())
+
         self.pages[language.name] = page
 
     def _build_readmes(self) -> None:

generate_docs/repo.py

@@ -9,6 +9,7 @@
 
 import os
 import re
+import yaml
 from typing import Optional
 
 
@@ -135,7 +136,7 @@ def _generate_urls(self) -> None:
     def _organize_collection(self):
         self.sample_programs.sort(key=lambda program: program.normalized_name.casefold())
 
-    def get_readable_name(self):
+    def get_readable_name(self) -> str:
         """
         Generates as close to the proper language name as possible given a language
         name in plain text separated by hyphens
@@ -154,6 +155,13 @@ def get_readable_name(self):
         else:
             return " ".join(tokens).title()
 
+    def get_test_data(self) -> Optional[dict]:
+        test_data = None
+        if self.test_file_path:
+            with open(os.path.join(self.path, self.test_file_path)) as test_file:
+                test_data = yaml.safe_load(test_file)
+        return test_data
+
 
 class SampleProgram:
     """
@@ -171,6 +179,7 @@ def __init__(self, path: str, file_name: str, language: str):
         self.file_name = file_name
         self.language = language
         self.sample_program_doc_url: Optional[str] = None
+        self.sample_program_req_url: Optional[str] = None
         self.sample_program_issue_url: Optional[str] = None
         self.normalized_name: Optional[str] = None
         self._generate_urls()
@@ -193,11 +202,12 @@ def get_language(self) -> str:
     def _normalize_program_name(self):
         stem = os.path.splitext(self.file_name)[0]
         if len(stem.split("-")) > 1:
-            url = stem
+            url = stem.lower()
         elif len(stem.split("_")) > 1:
-            url = stem.replace("_", "-")
+            url = stem.replace("_", "-").lower()
         else:
-            url = "-".join(re.findall('[a-zA-Z][^A-Z]*', stem)).lower()
+            # TODO: this is brutal. At some point, we should loop in the glotter test file.
+            url = re.sub('((?<=[a-z])[A-Z0-9]|(?!^)[A-Z](?=[a-z]))', r'-\1', stem).lower()
         return url
 
     def _generate_urls(self) -> None:
@@ -207,8 +217,14 @@ def _generate_urls(self) -> None:
 
         self.normalized_name = self._normalize_program_name()
 
+        # req URL
+        if "export" in self.normalized_name or "import" in self.normalized_name:
+            self.sample_program_req_url = f"{doc_url_base}/import-export"
+        else:
+            self.sample_program_req_url = f"{doc_url_base}/{self.normalized_name}"
+
         # doc URL
-        self.sample_program_doc_url = f"{doc_url_base}/{self.normalized_name}/{self.language}"
+        self.sample_program_doc_url = f"{self.sample_program_req_url}/{self.language}"
 
         # issue URL
         program = self.normalized_name.replace("-", "+")

setup.py

@@ -5,14 +5,17 @@
 
 setuptools.setup(
     name="generate_docs",
-    version="2.1.0",
+    version="2.2.0",
     author="The Renegade Coder",
     author_email="jeremy.grifski@therenegadecoder.com",
     description="A docs generation package for the Sample Programs repo",
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://github.com/TheRenegadeCoder/sample-programs-docs-generator",
     packages=setuptools.find_packages(),
+    install_requires=[
+        "PyYAML~=5.4.1"
+    ],
     entry_points={
         "console_scripts": [
             'wikig = generate_docs.generator:main_wiki',