diff --git a/docs/src/docs_best_practices/how-to/compile.md b/docs/src/docs_best_practices/how-to/compile.md index 1b7bd3bb..bafa85a3 100644 --- a/docs/src/docs_best_practices/how-to/compile.md +++ b/docs/src/docs_best_practices/how-to/compile.md @@ -1,29 +1,32 @@ # Compile and View Documentation Locally ## Step 0a: Update Docs Environment (First Time) + The first time you compile documentation for a package, make sure the `docs/` environment (i.e., `docs/Manifest.toml`, not the main `Manifest.toml` in the root of the repository) is pointing to your local version of the package, so it compiles your local changes: -```julia +``` julia --project=docs using Pkg Pkg.develop(path = "..") ``` ## Step 0b: Auto-Generate Structs (If Needed) + Most documentation changes are made directly to markdown (.md) files, but if you changed one of Sienna's .json descriptor files, you must first [follow the instructions here](@ref "Auto-Generation of Component Structs") to auto-generate the structs from the .json to have your changes propagated into the markdown files used for -documentation. +documentation. **Example**: You updated `PowerSystems.jl`' [`power_system_structs.json`](https://github.com/NREL-Sienna/PowerSystems.jl/blob/main/src/descriptors/power_system_structs.json) file. From a terminal at the root of the repository (i.e., `PowerSystems.jl`), run: -```julia + +``` julia --project=. using InfrastructureSystems InfrastructureSystems.generate_structs( @@ -33,8 +36,10 @@ InfrastructureSystems.generate_structs( ``` ## Step 0c: Run the Formatter (Before Submitting a Pull Request) + To automatically format the documentation to conform with the [style guide](@ref style_guide), run in a terminal at the root of the repository: + ``` julia scripts/formatter/formatter_code.jl ``` @@ -43,11 +48,12 @@ Resolve any errors and re-run until error-free. See how to [Troubleshoot Common for help. This is not a necessary step to compile, but needs to be done at least once to pass pull -request checks. +request checks. ## Step 1: Compile To compile, run in a terminal at the root of the repository: + ``` julia --project=docs docs/make.jl ``` @@ -56,8 +62,9 @@ Resolve any errors and re-run until error-free. See how to [Troubleshoot Common for help. ## Step 2: View + Click on the newly-created `index.html` file (e.g., `SomeSiennaPackage/docs/build/index.html`) to view your locally compiled documentation in a -browser. +browser. Visually verify formatting and that code blocks compile as expected. diff --git a/docs/src/docs_best_practices/how-to/general_formatting.md b/docs/src/docs_best_practices/how-to/general_formatting.md index bd8f9305..2e137e83 100644 --- a/docs/src/docs_best_practices/how-to/general_formatting.md +++ b/docs/src/docs_best_practices/how-to/general_formatting.md @@ -1,4 +1,4 @@ -# Clean Up General Formatting +# Clean Up General Formatting These recommendations are to make navigating our documentation effortless for users, while addressing common markdown formatting issues in the existing Sienna documentation: @@ -7,28 +7,39 @@ addressing common markdown formatting issues in the existing Sienna documentatio All package names, types, functions, methods, and parameters, etc. should formatted in back-ticks: + !!! tip "Do" + ``` `max_active_power` ``` + compiles as `max_active_power` -!!! warning "Don't" + +!!! warning "Don't" + ``` max_active_power ``` + compiles as max_active_power ## [Put hyperlinks everywhere](@id hyperlinks) + All types, function, and methods should have hyperlinks to the correct docstring, accounting for multiple methods of the same name due to Julia's multiple dispatch. [`Documenter.jl`](https://documenter.juliadocs.org/stable/) will link to the first occurrance in documentation. If that's not the one you're referring to, copy the entire signature with types into the hyperlink reference. + !!! tip "Do" + ``` [`get_time_series_values`](@ref) ``` + Or + ``` [`get_time_series_values` from a `ForecastCache`](@ref get_time_series_values( owner::TimeSeriesOwners, @@ -38,29 +49,36 @@ signature with types into the hyperlink reference. ignore_scaling_factors = false, )) ``` -!!! warning "Don't" - ``` - `get_time_series_values` - ``` - Or - ``` - get_time_series_values - ``` + +!!! warning "Don't" + + +``get_time_series_values`` +Or +`get_time_series_values` ## Add links to other Sienna packages All other Sienna package names should have documentation (not Git repo) hyperlinks: + !!! tip "Do" - ``` [`PowerSystems.jl`](https://nrel-sienna.github.io/PowerSystems.jl/stable/) ``` -!!! warning "Don't" + + ```[`PowerSystems.jl`](https://nrel-sienna.github.io/PowerSystems.jl/stable/)``` + +!!! warning "Don't" + ``` `PowerSystems.jl` ``` + Or + ``` PSY ``` + Or + ``` [`PowerSystems.jl`](https://github.com/NREL-Sienna/PowerSystems.jl) ``` diff --git a/docs/src/docs_best_practices/how-to/requirements_checklist.md b/docs/src/docs_best_practices/how-to/requirements_checklist.md index 9ca99e75..d39608cb 100644 --- a/docs/src/docs_best_practices/how-to/requirements_checklist.md +++ b/docs/src/docs_best_practices/how-to/requirements_checklist.md @@ -3,7 +3,7 @@ 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/). +[`JuliaFormatter.jl`](https://domluna.github.io/JuliaFormatter.jl/stable/). ## For New Packages @@ -15,21 +15,24 @@ required environments and formatting and documentation code. Start from this tem 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/) + 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 + + + How to [Write a How-to Guide](@ref) + + How to [Write a Tutorial](@ref) + + How to [Organize APIs and Write Docstrings](@ref) + + 2. Replace `compat` requirements of `Documenter = "0.27"` in `docs/` environment with `Documenter = "1.0"` -1. Update the `docs/make.jl` file to call + 3. 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 + + + See How-to [Troubleshoot Common Errors](@ref) if this results in a host of errors. + 4. 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. + for examples of the updated lines. diff --git a/docs/src/docs_best_practices/how-to/view_github.md b/docs/src/docs_best_practices/how-to/view_github.md index d8f53f3a..78d9ce3a 100644 --- a/docs/src/docs_best_practices/how-to/view_github.md +++ b/docs/src/docs_best_practices/how-to/view_github.md @@ -1,6 +1,8 @@ # View Draft Documentation on Github -1. Create a pull request on Github. -2. Verify the Documentation/build check was successful (takes a few minutes). -2. Preview it in a browser following this url format: - > https://nrel-sienna.github.io/.jl/previews/PR/ \ No newline at end of file + 1. Create a pull request on Github. + + 2. Verify the Documentation/build check was successful (takes a few minutes). + 3. Preview it in a browser following this url format: + + > https://nrel-sienna.github.io/.jl/previews/PR/ diff --git a/docs/src/docs_best_practices/how-to/write_a_how-to.md b/docs/src/docs_best_practices/how-to/write_a_how-to.md index 2544775e..78ab5ad7 100644 --- a/docs/src/docs_best_practices/how-to/write_a_how-to.md +++ b/docs/src/docs_best_practices/how-to/write_a_how-to.md @@ -5,11 +5,11 @@ problem or series of linked problems. ## Prepare -- If you have not read [Diataxis](https://diataxis.fr/), first read it in its entirety. -- If you have read it, skim the pages on [How-to guides](https://diataxis.fr/how-to-guides/) and + - If you have not read [Diataxis](https://diataxis.fr/), first read it in its entirety. + - If you have read it, skim the pages on [How-to guides](https://diataxis.fr/how-to-guides/) and the [difference between a tutorial and how-to guide](https://diataxis.fr/tutorials-how-to/) - to refresh your memory and refer back throughout the process. -- Look at an example: this page, how to [Compile and View Documentation Locally](@ref), and + to refresh your memory and refer back throughout the process. + - Look at an example: this page, how to [Compile and View Documentation Locally](@ref), and how to [Troubleshoot Common Errors](@ref) are all examples. ## Follow the Do's and Don't's @@ -25,53 +25,74 @@ Depth = 3:3 ``` ### Omit the Unnecessary -!!! tip "Do" - Jump the user right to a logical starting point in the code using `#hide` or - [`@setup`](https://documenter.juliadocs.org/stable/man/syntax/#reference-at-setup) - blocks. + +!!! tip "Do" + + +Jump the user right to a logical starting point in the code using `#hide` or +[`@setup`](https://documenter.juliadocs.org/stable/man/syntax/#reference-at-setup) +blocks. + !!! tip "Do" + [Configure the logger](@ref log) or load/build a `System` that returns very - few log statements. Use semi-colons at line ends to hide return statements if need be. + few log statements. Use semi-colons at line ends to hide return statements if need be. ### Make it effortless to read + !!! tip "Do" + Split code examples into ideally 1 (to 3) lines ONLY, with a short preface to explain what each line is doing, even if it's obvious to you. ### Move Docstring Material to the APIs + An issue with earlier versions of Sienna documentation was basic reference information located in pages other than the APIs. See how-to [Organize APIs and Write Docstrings](@ref) if needed to make that information easier to find. + !!! tip "Do" + Preface each call to a new function with a hyperlink to that function's - docstring so the user can find more detail + docstring so the user can find more detail + !!! warning "Don't" + Include digressive details about different keyword arguments or versions of - a function. + a function. ### Minimize or Eliminate How-To Guides with a Single Step + A how-to guide has a *sequence* of steps -- if your guide only has a single step, ask yourself if you are compensating for a lack of information in the API's. + !!! tip "Do" + Move how-to guides with a single function to being Examples in that function's docstring. See [Writing Documentation](@extref). ### Remove Other Reference Material + Particularly when editing existing pages, watch out for other [Reference](https://diataxis.fr/reference/) material. + !!! tip "Do" + Move tables and lists of information into Reference pages and link to them instead ### Follow the Guidelines on Cleaning Up General Formatting !!! tip "Do" - Follow How-to [Clean Up General Formatting](@ref). + + Follow How-to [Clean Up General Formatting](@ref). ### Look at the compiled .html! + !!! tip "Do" - - [Compile](@ref "Compile and View Documentation Locally") the how-to guide regularly and + + - [Compile](@ref "Compile and View Documentation Locally") the how-to guide regularly and look at it - - Check all code examples gave the expected results without erroring - - Check for length of the code examples and iteratively adjust to make it easy + - Check all code examples gave the expected results without erroring + - Check for length of the code examples and iteratively adjust to make it easy to read diff --git a/docs/src/docs_best_practices/how-to/write_a_tutorial.md b/docs/src/docs_best_practices/how-to/write_a_tutorial.md index 3f5ee62b..b641ae1e 100644 --- a/docs/src/docs_best_practices/how-to/write_a_tutorial.md +++ b/docs/src/docs_best_practices/how-to/write_a_tutorial.md @@ -1,18 +1,19 @@ # Write a Tutorial Tutorials are learning experiences to give our users confidence and experience in using -Sienna. +Sienna. ## Prepare -- If you have not read [Diataxis](https://diataxis.fr/), first read it in its entirety. -- If you have read it, skim the pages on [Tutorials](https://diataxis.fr/tutorials/) and + - If you have not read [Diataxis](https://diataxis.fr/), first read it in its entirety. + - If you have read it, skim the pages on [Tutorials](https://diataxis.fr/tutorials/) and the [difference between a tutorial and how-to guide](https://diataxis.fr/tutorials-how-to/) - to refresh your memory and refer back throughout the process. -- Look at an example: `PowerSystems.jl`'s + to refresh your memory and refer back throughout the process. + - Look at an example: `PowerSystems.jl`'s [Working with Time Series](https://nrel-sienna.github.io/PowerSystems.jl/stable/tutorials/working_with_time_series/) !!! warning + Historically, many of Sienna's "tutorials" have blended all 4 types of documentation in the [Diataxis](https://diataxis.fr/) framework. Be prepared to move material to related Explanation and How-to pages and into function docstrings in the APIs as you work. @@ -37,21 +38,27 @@ Depth = 3:3 The tutorial should have a logical flow, rather than be a series of disconnected code demonstrations. + !!! tip "Do" + Use either named [`@example`](https://documenter.juliadocs.org/stable/man/syntax/#reference-at-example) or named [`@repl`](https://documenter.juliadocs.org/stable/man/syntax/#@repl-block) blocks to ensure all code compiles in order in the same environment and ensuring each step builds on the previous steps in your story: + ````markdown ```@example my_tutorial ``` ```` + !!! warning "Don't" + Use a series of `julia` markdown blocks. These won't be compiled, failing the - intention of a tutorial and introducing high likelihood of errors as syntax changes. + intention of a tutorial and introducing high likelihood of errors as syntax changes. + ````markdown ```julia @@ -59,59 +66,84 @@ demonstrations. ```` ### Make it reproducible + A user should be able to copy and paste every code block in the tutorial in order and get -the exact results seen on the documentation page. +the exact results seen on the documentation page. + !!! tip "Do" - Display all code, starting from `using SomeSiennaPackage` -!!! warning "Don't" + + Display all code, starting from `using SomeSiennaPackage` + +!!! warning "Don't" + Use `#hide` or [`@setup`](https://documenter.juliadocs.org/stable/man/syntax/#reference-at-setup) blocks. ### Make it effortless to read + !!! tip "Do" + Split code examples into ideally 1 (to 3) lines ONLY, with a short preface to explain what each line is doing, even if it's obvious to you. -!!! warning "Don't" + +!!! warning "Don't" + Use blocks of example code and/or return statements that go over 1 screen length in the compiled .html. They are very hard to follow and allow a user to tune out or give up. ### Make it realistic and relatable + !!! tip "Do" - Take the time to define some realistic example data. -!!! warning "Don't" + + Take the time to define some realistic example data. + +!!! warning "Don't" + Use `zero()` or `one()` for all example data. ### Only show relevant log and return statements + !!! tip "Do" + [Configure the logger](@ref log) or load/build a `System` that returns very - few log statements. Use semi-colons at line ends to hide return statements if need be. -!!! warning "Don't" + few log statements. Use semi-colons at line ends to hide return statements if need be. + +!!! warning "Don't" + Show extensive or confusing log or return statements that bog down a reader with information that isn't directly relevant to what you're trying to teach. ### Remove other types of documentation + Particularly when editing existing material, watch out for material that should be moved elsewhere according to Diataxis principles: + !!! tip "Do" + Preface each call to a new function with a hyperlink to that function's - docstring so the user can find more detail + docstring so the user can find more detail + !!! warning "Don't" + Include definitions and details about different keyword arguments or versions of - a function in the tutorial itself. Some basic information is OK, but details and - examples live in the docstrings, and they especially shouldn't be included in the - tutorial **in lieu of** being in the docstrings. + a function in the tutorial itself. Some basic information is OK, but details and + examples live in the docstrings, and they especially shouldn't be included in the + tutorial **in lieu of** being in the docstrings. ### Follow the Guidelines on Cleaning Up General Formatting !!! tip "Do" - Follow How-to [Clean Up General Formatting](@ref). + + Follow How-to [Clean Up General Formatting](@ref). ### Look at the compiled .html! + !!! tip "Do" - - [Compile](@ref "Compile and View Documentation Locally") the tutorial regularly and + + - [Compile](@ref "Compile and View Documentation Locally") the tutorial regularly and look at it - - Check all code examples gave the expected results without erroring - - Check for length of the code examples and iteratively adjust to make it easy + - Check all code examples gave the expected results without erroring + - Check for length of the code examples and iteratively adjust to make it easy to read diff --git a/docs/src/docs_best_practices/how-to/write_docstrings_org_api.md b/docs/src/docs_best_practices/how-to/write_docstrings_org_api.md index c5e4ee70..77cc191a 100644 --- a/docs/src/docs_best_practices/how-to/write_docstrings_org_api.md +++ b/docs/src/docs_best_practices/how-to/write_docstrings_org_api.md @@ -7,14 +7,14 @@ guidance on common problems in our existing documentation. ## Prepare -- If you have not read [Diataxis](https://diataxis.fr/), first read it in its entirety. -- Refer back to the Diataxis [Reference](https://diataxis.fr/reference/) section while + - If you have not read [Diataxis](https://diataxis.fr/), first read it in its entirety. + - Refer back to the Diataxis [Reference](https://diataxis.fr/reference/) section while working. -- Read and follow Julia's guidance on [Writing Documentation](@extref), + - Read and follow Julia's guidance on [Writing Documentation](@extref), which mainly applies to docstrings -- Read the sections on `Documenter.jl`'s [`@docs` block](@extref) and + - Read the sections on `Documenter.jl`'s [`@docs` block](@extref) and [`@autodocs` block](@extref), and follow the guidance below on using `@autodocs` - wherever possible + wherever possible ## Follow the Do's and Don't's @@ -28,14 +28,17 @@ Depth = 3:3 ``` ### Look at the compiled .html! + !!! tip "Do" - - [Compile](@ref "Compile and View Documentation Locally") regularly and + + - [Compile](@ref "Compile and View Documentation Locally") regularly and look at the APIs - - Check method signatures and argument lists are formatted correctly + - Check method signatures and argument lists are formatted correctly ### Ensure All Docstrings Are Located in the APIs !!! tip "Do" + Include a Public API markdown file for exported structs, functions, and methods, and an Internals API for private functions. See [`PowerSystems.jl`](https://nrel-sienna.github.io/PowerSystems.jl/stable/) @@ -44,17 +47,21 @@ Depth = 3:3 template when starting a new package. !!! tip "Do" - Migrate all existing Formulation Libraries and Model Libraries into the Public API. + + Migrate all existing Formulation Libraries and Model Libraries into the Public API. !!! tip "Do" + If you want to make a docstring visible outside of the API (e.g., in a tutorial), use - a [non-canonical reference](@extref noncanonical-block). + a [non-canonical reference](@extref noncanonical-block). ### [Automate Adding Docstrings in the Public API with `@autodocs`](@id use_autodocs) !!! tip "Do" + Use [`@autodocs` block](@extref)s in the Public API markdown file to automatically find all docstrings in a file. Example: + ````markdown ## Variables ```@autodocs @@ -66,9 +73,11 @@ Depth = 3:3 ```` !!! warning "Don't" + Manually list out the struts or methods on a topic in a [`@docs` block](@extref), because that introduces more work whenever we add something new or make a change. Example: + ````markdown ## Variables ```@docs @@ -76,19 +85,21 @@ Depth = 3:3 variable2 ``` ```` + Consider re-organizing code if need be, so all related functions are in the same file(s) (e.g., `variables.jl`). ### [Selectively Export Docstrings from `InfrastructureSystems.jl`](@id docs_from_is) If you are working in another Sienna package (e.g., `SomeSiennaPackage.jl`) that imports and -exports code from `InfrastructureSystems.jl`: +exports code from `InfrastructureSystems.jl`: !!! tip "Do" + List the files containing necessary `InfrastructureSystems.jl` structs and methods in `SomeSiennaPackage.jl`'s Public API markdown file, then explicitly filter by what `SomeSiennaPackage.jl` exports. Example: - + ````markdown ```@autodocs Modules = [InfrastructureSystems] @@ -101,50 +112,56 @@ exports code from `InfrastructureSystems.jl`: ```` !!! warning "Don't" + List `InfrastructureSystems` as one of the `modules` in [`Documenter.makedocs`](@extref) in the `make.jl` file. `Documenter.jl` will look to map **all** `InfrastructureSystems.jl` docstrings into the API, resulting in hundreds of [missing docstring](@ref miss_doc) errors. Example: - + ```julia - makedocs( - modules = [SomeSiennaPackage, InfrastructureSystems], - format = Documenter.HTML( - prettyurls = haskey(ENV, "GITHUB_ACTIONS"), - size_threshold = nothing), - sitename = "SomeSiennaPackage.jl", - pages = Any[p for p in pages], + makedocs(; + modules = [SomeSiennaPackage, InfrastructureSystems], + format = Documenter.HTML(; + prettyurls = haskey(ENV, "GITHUB_ACTIONS"), + size_threshold = nothing), + sitename = "SomeSiennaPackage.jl", + pages = Any[p for p in pages], ) ``` ### Ensure All Docstrings Have a Function Signature and Arguments List !!! tip "Do" + Check all exported docstrings have a function signature and detailed arguments list *visible in the API when you compile it*. Example: - + ![A docstring with function signature and args list](../../assets/comp_after.png) !!! warning "Don't" + Leave docstrings that just have a description unaddressed. Example: - + ![A single line docstring](../../assets/comp_before.png) ### Automate Updating Docstring Arguments Lists + This is not commonly done in Sienna yet, but a goal is to improve our use of [`DocStringExtensions.jl`](https://docstringextensions.juliadocs.org/stable) for automation: !!! tip "Do" + Use [`DocStringExtensions.TYPEDFIELDS`](https://docstringextensions.juliadocs.org/stable/#DocStringExtensions.TYPEDFIELDS) to automatically compile arguments lists. Example: + ````markdown """ SomeSiennaStruct(arg1, arg2) # Arguments $(TYPEDFIELDS) - + This is the docstring line. """ struct SomeSiennaStruct <: OperationalCost @@ -156,14 +173,16 @@ This is not commonly done in Sienna yet, but a goal is to improve our use of ```` !!! warning "Don't" + Copy and paste arguments lists into the docstring, which opens opportunity for out-of-date errors when arguments are added or reordered. Example: + ````markdown """ SomeSiennaStruct(arg1, arg2) - + This is the docstring line. - + # Arguments - `arg2::Float64`: Documentation for argument 2 - `arg1::ProductionVariableCostCurve`: Documentation for argument 1 @@ -174,13 +193,15 @@ This is not commonly done in Sienna yet, but a goal is to improve our use of end ```` -### Add `See also` Links to Functions with the Same Name +### Add `See also` Links to Functions with the Same Name !!! tip "Do" + To help users navigate Julia's multiple dispatch, add `See also` paragraphs at the bottom of function docstrings other versions of the function with the same name, using the guidance on [adding a specific hyperlink](@ref hyperlinks). Example: + ``` See also [`get_time_series_array` by name from storage](@ref get_time_series_array( @@ -204,5 +225,6 @@ This is not commonly done in Sienna yet, but a goal is to improve our use of ### Follow the Guidelines on Cleaning Up General Formatting !!! tip "Do" + Follow How-to [Clean Up General Formatting](@ref), especially by adding hyperlinks to other Sienna structs that appear within an arguments list. diff --git a/docs/src/docs_best_practices/reference/useful_links.md b/docs/src/docs_best_practices/reference/useful_links.md index db8b74f2..7d1bc865 100644 --- a/docs/src/docs_best_practices/reference/useful_links.md +++ b/docs/src/docs_best_practices/reference/useful_links.md @@ -1,11 +1,11 @@ # Useful Links -- [Diataxis](https://diataxis.fr/): Reference for the new + - [Diataxis](https://diataxis.fr/): Reference for the new documentation framework Sienna is striving to follow (not specific to Julia) -- Julia's guidance on [Writing Documentation](@extref) -- [`Documenter.jl`](https://documenter.juliadocs.org/stable/): Julia's documentation + - Julia's guidance on [Writing Documentation](@extref) + - [`Documenter.jl`](https://documenter.juliadocs.org/stable/): Julia's documentation package, the [Syntax](https://documenter.juliadocs.org/stable/man/syntax/) and [Showcase](https://documenter.juliadocs.org/stable/showcase/) pages are especially useful -- [`SiennaTemplate.jl` Git repository](https://github.com/NREL-Sienna/SiennaTemplate.jl): A + - [`SiennaTemplate.jl` Git repository](https://github.com/NREL-Sienna/SiennaTemplate.jl): A template for new Sienna packages that includes the required documentation framework.