Finish requirements as how-to

docs/make.jl

@@ -27,15 +27,15 @@ pages = OrderedDict(
         "Documentation Best Practices" => Any[
             "Explanation" => "docs_best_practices/explanation.md",
             "How to..." => Any[
+                "Complete Basic Requirements Checklist" => "docs_best_practices/how-to/requirements_checklist.md",
                 "Clean Up General Formatting" => "docs_best_practices/how-to/general_formatting.md",
                 "Write a Tutorial" => "docs_best_practices/how-to/write_a_tutorial.md",
                 "Write a How-To Guide" => "docs_best_practices/how-to/write_a_how-to.md",
                 "Organize APIs and Write Docstrings" => "docs_best_practices/how-to/write_docstrings_org_api.md",
                 "Troubleshoot Common Errors" => "docs_best_practices/how-to/troubleshoot.md",
                 "Compile and View Documentation Locally" => "docs_best_practices/how-to/compile.md",
                 "View Draft Documentation on Github" => "docs_best_practices/how-to/view_github.md",],
-            "Reference" => Any["docs_best_practices/reference/requirements_checklist.md",
-                "docs_best_practices/reference/useful_links.md",],
+            "Reference" => Any["docs_best_practices/reference/useful_links.md",],
         ],
         "API" => "InfrastructureSystems.md"
 )

docs/src/docs_best_practices/how-to/requirements_checklist.md

@@ -0,0 +1,35 @@
+# Complete Basic Requirements Checklist
+
+Sienna packages should follow the [Diataxis](https://diataxis.fr/)
+framework, be strictly compiled with [`Documenter.jl`](https://documenter.juliadocs.org/stable/)
+v1.0 or greater, and be automatically formatted with
+[`JuliaFormatter.jl`](https://domluna.github.io/JuliaFormatter.jl/stable/). 
+
+## For New Packages
+
+The [`SiennaTemplate.jl`](https://github.com/NREL-Sienna/SiennaTemplate.jl) Git repo has the
+required environments and formatting and documentation code. Start from this template.
+
+## For Existing Packages
+
+Existing Sienna packages will need to be updated with these requirements, but these will
+only need to be addressed once:
+
+1. Organize the top-level documentation to follow the [Diataxis](https://diataxis.fr/)
+    framework (plus a welcome page/section). This might be a significant undertaking. See:
+    - How to [Write a How-to Guide](@ref)
+    - How to [Write a Tutorial](@ref)
+    - How to [Organize APIs and Write Docstrings](@ref)
+1. Replace `compat` requirements of `Documenter = "0.27"` in `docs/` environment with
+    `Documenter = "1.0"`
+1. Update the `docs/make.jl` file to call
+    [`Documenter.makedocs`](https://documenter.juliadocs.org/stable/lib/public/#Documenter.makedocs)
+    *without* the `warnonly` `kwarg` (i.e., all errors caught by `makedocs` must be resolved before
+    merging). [See an example here](https://github.com/NREL-Sienna/InfrastructureSystems.jl/blob/768438a40c46767560891ec493cf87ed232a2b2b/docs/make.jl#L47).
+    - See How-to [Troubleshoot Common Errors](@ref) if this results in a host of errors. 
+1. Update the `scripts/formatter/formatter_code.jl` to format the markdown .md files in the
+    `docs/` folder, calling `format`() with the `kwarg` `format_markdown = true`. See
+    [these](https://github.com/NREL-Sienna/InfrastructureSystems.jl/blob/768438a40c46767560891ec493cf87ed232a2b2b/scripts/formatter/formatter_code.jl#L13)
+    [three](https://github.com/NREL-Sienna/InfrastructureSystems.jl/blob/768438a40c46767560891ec493cf87ed232a2b2b/scripts/formatter/formatter_code.jl#L8)
+    [links](https://github.com/NREL-Sienna/InfrastructureSystems.jl/blob/768438a40c46767560891ec493cf87ed232a2b2b/scripts/formatter/formatter_code.jl#L23)
+    for examples of the updated lines.