Add the --no-examples option to remove sample content; #4

Author: msuchane

src/cmd_line.rs

@@ -72,6 +72,13 @@ pub fn get_args() -> ArgMatches<'static> {
                 .long("no-comments")
                 .help("Generate the file without any comments"),
         )
+        .arg(
+            Arg::with_name("no-examples")
+                .short("E")
+                .long("no-examples")
+                .alias("expert-mode")
+                .help("Generate the file without any example, placeholder content"),
+        )
         .arg(
             Arg::with_name("detect-directory")
                 .short("D")

src/main.rs

@@ -10,6 +10,7 @@ use module::{Input, Module, ModuleType};
 pub struct Options {
     comments: bool,
     prefixes: bool,
+    examples: bool,
     target_dir: String,
     detect_directory: bool,
 }
@@ -22,8 +23,9 @@ fn main() {
         // Comments and prefixes are enabled (true) by default unless you disable them
         // on the command line. If the no-comments or no-prefixes option is passed
         // (occurences > 0), the feature is disabled, so the option is set to false.
-        comments: cmdline_args.occurrences_of("no-comments") == 0,
-        prefixes: cmdline_args.occurrences_of("no-prefixes") == 0,
+        comments: !cmdline_args.is_present("no-comments"),
+        prefixes: !cmdline_args.is_present("no-prefixes"),
+        examples: !cmdline_args.is_present("no-examples"),
         // Set the target directory as specified or fall back on the current directory
         target_dir: if let Some(dir) = cmdline_args.value_of("target-dir") {
             String::from(dir)

src/module.rs

@@ -255,9 +255,34 @@ impl Input {
 
             template_with_replacements =
                 template_with_replacements.replace("${include_statements}", &includes_text);
-        } else {
+        } else if self.options.examples {
             template_with_replacements = template_with_replacements
                 .replace("${include_statements}", "Include modules here.");
+        } else {
+            template_with_replacements = template_with_replacements
+                .replace("${include_statements}\n", "");
+        }
+
+        // If the `--no-examples` option is active, remove all lines between the <example> tags.
+        if !self.options.examples {
+            let examples: Regex = RegexBuilder::new(r"^// <example>\n[\s\S]*\n^// </example>\n")
+                .multi_line(true)
+                .swap_greed(true)
+                .build()
+                .unwrap();
+            template_with_replacements = examples
+                .replace_all(&template_with_replacements, "")
+                .to_string();
+        // If the `--no-examples` option isn't active, remove just the <example> tags.
+        } else {
+            let example_tags: Regex = RegexBuilder::new(r"^// </?example>\n")
+                .multi_line(true)
+                .swap_greed(true)
+                .build()
+                .unwrap();
+            template_with_replacements = example_tags
+                .replace_all(&template_with_replacements, "")
+                .to_string();
         }
 
         // If comments are disabled via an option, delete comment lines from the content

templates/assembly.adoc

@@ -26,13 +26,17 @@ endif::[]
 :context: ${module_id}
 // The `context` attribute enables module reuse. Every module's ID includes {context}, which ensures that the module has a unique ID even if it is reused multiple times in a guide.
 
+// <example>
 This paragraph is the assembly introduction. It explains what the user will accomplish by working through the modules in the assembly and sets the context for the user story the assembly is based on. Can include more than one paragraph. Consider using the information from the user story.
+// </example>
 
 .Prerequisites
 
+// <example>
 * A bulleted list of conditions that must be satisfied before the user starts following this assembly.
 * You can also link to other modules or assemblies the user must follow before starting this assembly.
 * Delete the section title and bullets if the assembly has no prerequisites.
+// </example>
 
 // The following include statements pull in the module files that comprise the assembly. Include any combination of concept, procedure, or reference modules required to cover the user story. You can also include other assemblies.
 
@@ -46,9 +50,11 @@ ${include_statements}
 
 == Additional resources (or Next steps)
 
+// <example>
 * A bulleted list of links to other material closely related to the contents of the assembly, including xref links to other assemblies in your collection.
 * For more details on writing assemblies, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+// </example>
 
 // Restore the context to what it was before this assembly.
 ifdef::parent-context-of-${module_id}[:context: {parent-context-of-${module_id}}]

templates/concept.adoc

@@ -14,6 +14,7 @@
 // In the title of concept modules, include nouns or noun phrases that are used in the body text. This helps readers and search engines find the information quickly.
 // Do not start the title of concept modules with a verb. See also _Wording of headings_ in _The IBM Style Guide_.
 
+// <example>
 A short introductory paragraph is required for the concept module.
 It will provide an overview of the module.
 
@@ -22,11 +23,14 @@ The contents of a concept module give the user descriptions and explanations nee
 * Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.
 * Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.
 * Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.
+// </example>
 
 .Additional resources
 
+// <example>
 * A bulleted list of links to other material closely related to the contents of the concept module.
 * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
 * For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+// </example>
 

templates/procedure.adoc

@@ -13,29 +13,39 @@
 = ${module_title}
 // Start the title of a procedure module with a verb, such as Creating or Create. See also _Wording of headings_ in _The IBM Style Guide_.
 
+// <example>
 This paragraph is the procedure module introduction: a short description of the procedure.
+// </example>
 
 .Prerequisites
 
+// <example>
 * A bulleted list of conditions that must be satisfied before the user starts following this assembly.
 * You can also link to other modules or assemblies the user must follow before starting this assembly.
 * Delete the section title and bullets if the assembly has no prerequisites.
+// </example>
 
 .Procedure
 
+// <example>
 . Start each step with an active verb.
 . Include one command or action per step.
 . Use an unnumbered bullet (*) if the procedure includes only one step.
+// </example>
 
 .Verification steps
 
+// <example>
 . Optional: Provide the user with verification method(s) for the procedure, such as expected output or commands that can be used to check for success or failure.
 . Use an unnumbered bullet (*) if the procedure includes only one step.
+// </example>
 
 .Additional resources
 
+// <example>
 * A bulleted list of links to other material closely related to the contents of the procedure module.
 * Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module.
 * For more details on writing procedure modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
 * Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide].
+// </example>
 

templates/reference.adoc

@@ -13,6 +13,7 @@
 = ${module_title}
 // In the title of a reference module, include nouns that are used in the body text. For example, "Keyboard shortcuts for ___" or "Command options for ___." This helps readers and search engines find the information quickly.
 
+// <example>
 A short introductory paragraph is required for the reference module.
 It will provide an overview of the module.
 
@@ -37,4 +38,5 @@ Term 2:: Definition
 |Row 1, column 1|Row 1, column 2|Row 1, column 3
 |Row 2, column 1|Row 2, column 2|Row 2, column 3
 |====
+// </example>