Add docs

docs/creating-a-theme.md

@@ -0,0 +1,41 @@
+# Creating a theme
+
+A theme is a Jenkins plugin that includes:
+
+* 0 or more CSS files
+* 0 or more JavaScript files
+
+Theme discovery in Jenkins uses the [ThemeManagerFactory](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactory.java)
+extension point.
+
+## Getting started
+
+Create a plugin from the `empty plugin` [Jenkins archetype](https://github.com/jenkinsci/archetypes/).
+
+You will need to extend/implement:
+
+* [ThemeManagerFactory](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactory.java)
+* [ThemeManagerFactoryDescriptor](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactoryDescriptor.java)
+* [UnprotectedRootAction](https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/hudson/model/UnprotectedRootAction.java)
+
+Take a look at the [dark-theme-plugin](https://github.com/jenkinsci/dark-theme-plugin) for a sample implementation.
+
+You can find all the available variables provided by Jenkins core in [theme.less](https://github.com/jenkinsci/jenkins/blob/master/war/src/main/less/abstracts/theme.less). Plugins may also define their own variables so this list may not be complete, but it should cover most of them.
+
+Don't forget to add `@Extension` to your `descriptor` and `UnprotectedRootAction`.
+
+Add a symbol to your `descriptor` for a nice short name when using configuration-as-code, e.g. `@Symbol("neo2")`.
+
+## Testing your theme
+
+Run `mvn hpi:run` from your plugin directory, that will startup a test instance of Jenkins.
+
+Visit http://localhost:8080/jenkins in your browser and configure your theme from there.
+
+### Host your plugin
+
+Follow the [hosting guide](https://www.jenkins.io/doc/developer/publishing/requesting-hosting/).
+
+### Let others know about it
+
+Send a pull request to this plugin's README to add it to the known plugins list (once the plugin is in the Jenkins update center).

docs/developer-guide.md

@@ -1,41 +1,7 @@
-# How to create a theme
+# Developer guides
 
-A theme is a Jenkins plugin that includes:
+Step-by-step guides to implementing extension points of the Theme Manager plugin.
 
-* 0 or more CSS files
-* 0 or more JavaScript files
+- [Creating a theme](./creating-a-theme.md)
+- [Theme properties](./theme-properties.md)
 
-Theme discovery in Jenkins uses the [ThemeManagerFactory](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactory.java)
-extension point.
-
-## Getting started
-
-Create a plugin from the `empty plugin` [Jenkins archetype](https://github.com/jenkinsci/archetypes/).
-
-You will need to extend/implement:
-
-* [ThemeManagerFactory](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactory.java)
-* [ThemeManagerFactoryDescriptor](https://github.com/jenkinsci/theme-manager-plugin/blob/master/src/main/java/io/jenkins/plugins/thememanager/ThemeManagerFactoryDescriptor.java)
-* [UnprotectedRootAction](https://github.com/jenkinsci/jenkins/blob/master/core/src/main/java/hudson/model/UnprotectedRootAction.java)
-
-Take a look at the [dark-theme-plugin](https://github.com/jenkinsci/dark-theme-plugin) for a sample implementation.
-
-You can find all of the available variables provided by Jenkins core in [theme.less](https://github.com/jenkinsci/jenkins/blob/master/war/src/main/less/abstracts/theme.less). Plugins may also define their own variables so this list may not be complete but it should cover most of them.
-
-Don't forget to add `@Extension` to your `descriptor` and `UnprotectedRootAction`.
-
-Add a symbol to your `descriptor` for a nice short name when using configuration-as-code, e.g. `@Symbol("neo2")`.
-
-## Testing your theme
-
-Run `mvn hpi:run` from your plugin directory, that will startup a test instance of Jenkins.
-
-Visit http://localhost:8080/jenkins in your browser and configure your theme from there.
-
-### Host your plugin
-
-Follow the [hosting guide](https://www.jenkins.io/doc/developer/publishing/requesting-hosting/).
-
-### Let others know about it
-
-Send a pull request to this plugin's README to add it to the known plugins list (once the plugin is in the Jenkins update center).

docs/theme-properties.md

@@ -0,0 +1,45 @@
+# Theme properties
+
+Themes can set properties giving information about themselves.
+
+This can be useful when interfacing with other libraries like Prism or CodeMirror that have their own theming capability but need to know which theme to use.
+
+Instead of making a user select their theme for each library, themes can say which ones work best for them
+
+## Provider guide
+
+Inside your `#getTheme` method of your `ThemeManagerFactory` call:
+
+`builder#withProperty(artifactId, propertyName, propertyValue)`
+
+```java
+public class YourThemeManagerFactory {
+    public Theme getTheme() {
+        return Theme.builder()
+                .withCssUrl(getCssUrl())
+                .withProperty("prism-api", "theme", "tomorrow")
+                .build();
+    }
+}
+```
+
+The artifactId will be prepended to the property name with a : separator, this is to prevent any clashes between plugins.
+
+## Consumer guide
+
+Retrieve the active theme from `ThemeManagerPageDecorator`, a `NoOp` theme will be provided if none is selected.
+
+```java
+
+public class YourPluginCode {
+    public String getThemeName() {
+        Theme theme = ThemeManagerPageDecorator.get().findTheme();
+        return theme.getProperty("prism-api", "theme").orElse("prism");
+    }
+}
+
+```
+
+## Existing implementations
+
+- [Prism API](https://github.com/jenkinsci/prism-api-plugin/pull/41) - Uses the `theme` property to select which prism theme should be used by default