docs: 📝 add guide for contributing built-in styles

_quarto.yml

@@ -59,6 +59,7 @@ website:
             - docs/guide/cli.qmd
             - docs/guide/config.qmd
             - docs/guide/custom-styles.qmd
+            - docs/guide/contribute-built-in-style.qmd
 
 quartodoc:
   sidebar: "docs/reference/_sidebar.yml"

docs/guide/contribute-built-in-style.qmd

@@ -0,0 +1,110 @@
+---
+title: "Contributing a built-in style"
+description: "Add your own style as a built-in style in Flower."
+order: 4
+---
+
+Flower comes with a number of
+[built-in styles](/docs/design/interface/outputs.qmd#built-in-styles) to
+use with the `build` or `view` commands. This guide explains how to
+contribute a new built-in style that will be available to all Flower
+users.
+
+Before you begin, fork the Flower repository on GitHub and clone your
+fork locally. Make the following changes in your local copy.
+
+## Creating a new style
+
+Built-in styles consist of the following files:
+
+- Jinja2 template files: these define the layout of the generated
+  documentation.
+- A `sections.toml` configuration file: this defines how many output
+  files will be created and which metadata will be displayed in each
+  file.
+
+First,
+[create the template files](/docs/guide/custom-styles.qmd#creating-the-templates)
+and
+[add the `sections.toml` configuration file](/docs/guide/custom-styles.qmd#sections.toml-configuration-file)
+for your style by following the guide for creating custom styles. If you
+are writing a terminal style for use with the `view` command, do not put
+an `output-path` for your sections in `sections.toml`.
+
+Use the name of your style as the name of the template folder. The name
+should be short, descriptive, and distinct from existing built-in
+styles. It should be given in snake case.
+
+## Adding the style as built-in
+
+Next, in your local copy of the Flower repo, place the template folder
+into the `src/seedcase_flower/styles/` folder. The file structure should
+now look like:
+
+``` txt
+src/
+└── seedcase_flower/
+    └── styles/
+        ├── ...
+        └── your_new_style/
+            ├── sections.toml
+            ├── template_1.qmd.jinja
+            ├── template_2.qmd.jinja
+            ├── ...
+            └── template_last.qmd.jinja
+```
+
+Finally, add your style to the appropriate style enum (`BuildStyle` or
+`ViewStyle`) in `src/seedcase_flower/internals.py`. Styles used with the
+`build` command are defined in the `BuildStyle` enum, while styles used
+with `view` are defined in `ViewStyle`. For example, if the
+`your_new_style` is a style for `build`, you would include it like so:
+
+``` {.python filename="src/seedcase_flower/internals.py"}
+class BuildStyle(Enum):
+    """Built-in styles for outputting to file."""
+
+    quarto_one_page = "quarto_one_page"
+    quarto_resource_listing = "quarto_resource_listing"
+    quarto_resource_tables = "quarto_resource_tables"
+    your_new_style = "your_new_style" # <1>
+```
+
+1. Add your new style as shown on this line.
+
+::: callout-important
+For the new style to work properly, the name of the enum member must be
+exactly the same as the folder name for the new style.
+:::
+
+## Testing the new style
+
+Once the new style is in place, be sure to test that it works as
+expected by running the `view` or `build` command as appropriate. You
+can use the example Data Package included in Flower to test:
+
+``` {.bash filename="Terminal"}
+uv run seedcase-flower build --uri docs/includes/datapackage.json --style your-new-style
+```
+
+## Making a pull request
+
+Before submitting a pull request with your changes, make sure you:
+
+- Run `just run-all` in the terminal.
+- Put your changes on a new branch with a name that follows our
+  [branch naming conventions](https://guidebook.seedcase-project.org/workflows/prs#branch-naming-conventions).
+- Commit your changes following
+  [Conventional Commits](https://guidebook.seedcase-project.org/workflows/commits#conventional-commits).
+- Push your branch to GitHub.
+
+You might find it helpful to read through our
+[contributing guidelines](/CONTRIBUTING.html). If you would like a more
+detailed walkthrough of
+[creating commits](https://guidebook.seedcase-project.org/workflows/commits)
+and
+[submitting pull requests](https://guidebook.seedcase-project.org/workflows/prs),
+have a look at the relevant sections of our Guidebook.
+
+You're now ready to open a pull request from your fork to the main
+Flower repository on GitHub.