Ah - by mistake, I replied only to Bill. Cross-posting to the list as well. Sorry for the spam.

======

Hello there,

First - I found the current screencasts massively helpful in getting started, to be honest. They are something I really have not seen in most projects, and they contributed a lot to me making sense of the Keycloak codebase and usage scenarios. Kudos.

Sedond - I think it would be quite helpful to add additional modularization and also harmonize some configuration to make it more evident in how it is interpreted. Let me clarify the last bit here (I'll take themes as an example, but I believe that the same conclusion stands for other parts of the Keycloak codebase):

# Import and extend definitions
parent=base
import=common/keycloak
styles=lib/patternfly/css/patternfly.css lib/zocial/zocial.css stylesheets/login.css stylesheets/yourOwn.css

The documentation and examples provides something roughly similar to the above.
Turning the attention to the "import" parameter, one could jump to the conclusion that there would be directory called "common/keycloak" and that this directory should contain a lib directory containing the styles css documents from the "styles" configuration.
Reading the codebase, it seems that the semantics of the "import" property is something completetly different. From the ExtendingThemeManager::loadTheme, I can see that the '/' is instead used as a list separator implying that we should attempt loading resources from several sources. (Snippet pasted below).

if (theme.getImportName() != null) {
    String[] s = theme.getImportName().split("/");
    themes.add(findTheme(s[1], Theme.Type.valueOf(s[0].toUpperCase())));
}

So ... I would believe that the configuration in this case would be clearer on a Java Object, JSON or XML form, where one can provide somewhat better semantics than what is possible in a properties file (one could use a List of theme names instead of a single string value to be parsed and interpreted, for example).

Mind if I take a stab at implementing a suggestion here?

2015-08-09 17:25 GMT+02:00 Bill Burke <bburke@redhat.com>:

Only plans right now are to separate our public SPIs and APIs from our
private ones. This is a requirement by Red hat before we go into product.

Also, a massive backlog of requirements and feature requests has made us
rush documentation. The screencast videos haven't been updated since
January. It is what it is. Over the next 3-6 months we will catch up
on this stuff becuase we are required to before we go into Product.

FYI, we already autogenerate REST docs.

On 8/9/2015 7:38 AM, Lennart Jörelid wrote:
> Hello all,
>
> A month or so ago, I got curious about Keycloak. Downloaded, set up in a
> dev environment, created some custom themes and took a look at the
> codebase. I have a few questions, likely because I have missed some
> developer documentation:
>
> * *Codebase concepts*: I frequently try to structure codebases to
> highlight its big concepts. For example, if we consider 'themes' to
> be such a concept in KeyCloak we might create a folder called
> 'themes", with some project wihtin it: (themes-model, themes-spi,
> themes-impl-jpa, themes-impl-freemarker, ....). Is there a
> description of the codebase structure or concepts currently?
> ("mini-SAD")
> * *Codebase javadoc:* Do we have a policy for JavaDoc'ing the
> Model/API/SPI but perhaps not the implementation classes, other than
> with implementation details?
> * *Configuration:* Some of the descriptions in the docbook are really
> good, and some are more shallow. If we create a standard way of
> configuring the parts of keycloak, we could likely generate standard
> setup/configuration documentation (somewhat similar to maven plugins
> where certain parts of a site documentation is generated from
> annotations or JavaDocs). Are there such plans?
>
>
> --
>
> --
> +==============================+
> | Bästa hälsningar,
> | [sw. "Best regards"]
> |
> | Lennart Jörelid
> | EAI Architect & Integrator
> |
> | jGuru Europe AB
> | Mölnlycke - Kista
> |
> | Email:lj@jguru.se <mailto:lj@jguru.se>
> | URL:www.jguru.se <http://www.jguru.se>
> | Phone
> | (skype): jgurueurope
> | (intl): +46 708 507 603
> | (domestic): 0708 - 507 603
> +==============================+
>
>
>
> _______________________________________________
> keycloak-dev mailing list
> keycloak-dev@lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/keycloak-dev
>

--
Bill Burke
JBoss, a division of Red Hat
http://bill.burkecentral.com
_______________________________________________
keycloak-dev mailing list
keycloak-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/keycloak-dev

--
+==============================+
| Bästa hälsningar,
| [sw. "Best regards"]
|
| Lennart Jörelid
| EAI Architect & Integrator
|
| jGuru Europe AB
| Mölnlycke - Kista
|
| Email: lj@jguru.se
| URL:   www.jguru.se
| Phone
| (skype):    jgurueurope
| (intl):     +46 708 507 603
| (domestic): 0708 - 507 603
+==============================+