Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.Problem/Motivation
We have a ton of theme hooks/templates established through-out core and contrib themes. Often times it is unclear how to newcomers how the theme system works exactly. We need a better front facing sub-site for themes that can showcase rendered examples of it's "theme component library".
Proposed resolution
Create a module that automatically parses theme hooks and it's documentation (very similar to api.d.o) and shows the rendered examples in the theme itself.
Examples of "theme components sites":
http://pea.rs/
http://getbootstrap.com/css/#tables
This would be a new sub-domain with different core sub-sites, like: https://theme.drupal.org/7/ or https://theme.drupal.org/8/.
Remaining tasks
TBD
User interface changes
TBD
API changes
TBD
Original report by @Mark Carver
[05:46 PM] markcarver: mjwmeyer and I were discussing "theming documentation" earlier and it was shortly after I took the survey
[05:46 PM] markcarver: basically the jist of it is: we could, in theory, have an automated theme component library
[05:47 PM] mortendk: markcarver: yup
[05:47 PM] markcarver: it would be very similar to how api.d.o already parses DOXYGEN comments, but instead of just plain ol' text, we enable the theme when they're viewing the documentation
[05:47 PM] markcarver: this would allow themes to provide real rendered examples, including extending existing core theme hooks
[05:48 PM] mortendk: what i would love was a php parser of my scss files so i could get my documentation of my css out at the same time - so i could create style guides on the go
[05:48 PM] markcarver: similar to getbootstrap.com/css/#tables
[05:48 PM] markcarver: that's basically what I'm thinking, having a "theme specific" api site
[05:49 PM] markcarver: jenlampton: ^ fyi
[05:49 PM] jenlampton: mind. blown.
[05:50 PM] mortendk: markcarver: yup exactly
[05:50 PM] mortendk: well it should be possible
[05:50 PM] markcarver: just an idea now, obviously we can't "enable" every contributed theme
[05:50 PM] mjwmeyer: mortendk: that doesn't sound too difficult - you just have to pull out all the comments, right? Isn't that what the API module already does?
[05:50 PM] markcarver: it'd likely have to be an "opt in" via @themable or something
[05:51 PM] jenlampton: markcarver: maybe we can… crazy multi-site theme demo generator?
[05:51 PM] markcarver: mjwmeyer: api doesn't parse css/scss/less
[05:51 PM] jenlampton: based on latest stable in git?
[05:51 PM] markcarver: just PHP and now twig
[05:51 PM] markcarver: jenlampton: basically what I was thinking, yes
[05:51 PM] mjwmeyer: well, yeah, but how hard could it be to add those files? :P
[05:51 PM] markcarver: jenlampton: https://drupal.org/project/themekey
[05:51 PM] jenlampton: yeah
[05:51 PM] mortendk leans back and hopes to see magic happen
[05:51 PM] mjwmeyer: wow - all I was trying to do was figure out where to start documenting, and I've started a "thing" ;)
[05:52 PM] mortendk: mjwmeyer: check beware ;)
[05:53 PM] mortendk: we jumping on all the good ideas here ;)
[05:53 PM] jenlampton: markcarver may have been scheming on this “thing” for a while… sounds like a well thought through idea already!
[05:53 PM] mjwmeyer: that's one of the things I love about collaborating - it always generates tons of cool ideas
[05:53 PM] markcarver: ha, no actually it popped in my head when I was taking mortendk's survey
[05:53 PM] jenlampton: markcarver++
[05:54 PM] markcarver has TONS of ideas.... a few good ones here and there lol
[05:54 PM] mjwmeyer: jenlampton: yeah, he did seem to have a lot to say when I first brought up the idea of creating a "demo/example guide" for building a new theme in D8
[05:54 PM] mortendk: even blind chicken can find a corn ;)
[05:54 PM] markcarver: ha
[05:54 PM] mortendk: markcarver: heheh so glad translated hehe
[05:55 PM] markcarver: jenlampton: I was just thinking that I know we said we should probably do a theme "examples" module/theme w/e.... but we could kill two birds with one stone if we just setup a proper site that parses themes automatically and lets you view them as the theme I think
[05:55 PM] mjwmeyer: I like the idea - especially since it would let me easily see the existing documentation to look for where it needs to be improved
[05:55 PM] markcarver: and that's essentially the "theme component library"
[05:56 PM] mjwmeyer waves her hand royally Make it so!
[05:56 PM] markcarver: mjwmeyer: fwiw, I probably wouldn't get too serious about this until DC
[05:56 PM] mjwmeyer: when is that?
[05:56 PM] markcarver: I just wanted to float the idea around and see if it's viable
[05:57 PM] markcarver: June 1-8
[05:57 PM] mjwmeyer: not that far away
[05:57 PM] markcarver: I already plan on working on d.o before and after DC, so maybe I can haggle jthorson and a few others hehe
[05:58 PM] jenlampton: markcarver: did u envision something where people can view docs on theme_item_list and then run it through stark, bartik, or bootstrap?
[05:59 PM] jenlampton: or something much bigger like view api.d.o itself in that theme?
[06:00 PM] markcarver: jenlampton: no, more focused on the theme itself... like core has ABC and theme X inherits AB and overrides C and adds DEF
[06:00 PM] jenlampton: i think the latter is totally possible, but the former may be nearly impossible unless each theme function gets an attached library of assets
[06:00 PM] jenlampton: markcarver: oh.
[06:00 PM] markcarver: yeah, I was thinking we'd just render the entire site in the theme of their choice
[06:00 PM] jenlampton: how would that look?
[06:00 PM] markcarver: idk
[06:00 PM] markcarver: lol
[06:00 PM] mjwmeyer: I would think something more like "here's this theme function and how to use it", and "here's an example of how X theme uses it and changes ABC theme"
[06:01 PM] jenlampton: maybe theme developer style?
[06:01 PM] jenlampton: hm
[06:01 PM] markcarver: all I know is I'd like something like http://getbootstrap.com/css/#tables
[06:01 PM] jenlampton: whatever it is, I want it. we should work out the whatever over the next few months :)
[06:01 PM] mjwmeyer: but maybe I'm misunderstanding - my knowledge of theming at this point is very close to 0
[06:01 PM] markcarver: where it actually renders each "option" to show you the results in an actual table
[06:01 PM] markcarver: totally
[06:02 PM] mjwmeyer: ohhh... kind of like how some CSS tutorials do?
[06:02 PM] markcarver: kinda
[06:02 PM] mjwmeyer: here's how you use the bold tag. Here's what the bold tag looks like when it's used...
[06:02 PM] markcarver: we'd essentially also be integrating drupal.org/project/styleguide probably
[06:03 PM] markcarver: maybe, idk... I really don't like how that module currently implements things
[06:03 PM] markcarver: (deadarm inherited it)
[06:03 PM] jenlampton: it just calls theme functions and spits out the output
[06:03 PM] jenlampton: we had something nearly identical at ch3
[06:03 PM] markcarver: well yes, but the overall structure of the module and it's "API" could use a _lot_ of work
[06:03 PM] jenlampton: i could totally see that though
[06:03 PM] markcarver: IMO anyway
[06:04 PM] markcarver: I started my own styleguide module when I was at levelten
[06:04 PM] jenlampton: like - call theme_item_list and then theme_item_list__users
[06:04 PM] jenlampton: etc
[06:04 PM] markcarver: and even talked with deadarm about a "2.x" version
[06:04 PM] mjwmeyer: I think you're right that ThemeKey could be useful, since it has "content, user, or role-specific" themes
[06:04 PM] jenlampton: markcarver: I think everyone must have that same idea ;)
[06:04 PM] markcarver: but sigh... I need to git clone myself
[06:05 PM] markcarver: yeah
[06:05 PM] jenlampton: markcarver++
[06:05 PM] jenlampton: I like where this is going
[06:05 PM] markcarver: i love http://pea.rs/
[06:05 PM] mjwmeyer: so basically you would implement the theme with the given theme component content
[06:05 PM] jenlampton: esp if we can pepper it with documentation too
[06:06 PM] markcarver: essentially, yes
[06:06 PM] markcarver: yes, I could see this being very tied to api.d.o, but yet separate
[06:06 PM] markcarver: there's times when you need/want explicit raw documentation
[06:06 PM] mjwmeyer: would this be automated in that it would pull the docs from the code, or are we talking something more like the d.o documentation that is static on the site
[06:06 PM] jenlampton: yes yes yes
[06:07 PM] markcarver: but the front facing aspect needs to be more "obvious" so people like mjwmeyer can understand how drupal theming works :)
[06:07 PM] mjwmeyer: hehe
[06:07 PM] jenlampton: we need this.
[06:07 PM] mjwmeyer: that's why I'm here - to help with the newbie view ;)
[06:07 PM] markcarver: badly
[18:07:48] <markcarver> mjwmeyer: it would be automatic from code
[18:07:52] <markcarver> as api.d.o is
[18:09:54] <mjwmeyer> so how does this work now that we have a great idea... do we create an "issue" for this to do further discussion?
[18:10:11] <markcarver> mjwmeyer: good freaking idea...
[18:10:16] <mortendk> yup create an issue
Comments
Comment #1
mjwmeyer CreditAttribution: mjwmeyer commentedComment #2
markhalliwellComment #3
markhalliwellComment #4
markhalliwellComment #5
markhalliwellComment #6
LewisNymanI've been thinking something similar in #2102191: Discuss the availiable solutions to document the Seven style guide
My preference is to use an existing syntax like Knyle and just teach api.drupal.org to read it.
Comment #7
sunNote that there are two modules that (more or less) essentially try to achieve this, though in an actual Drupal site (using your actual theme):
https://drupal.org/project/styleguide
https://drupal.org/project/design
The design_test module of the Design project was actually part of D8 core for a short period of time. (It was introduced as a hidden core module in order to facilitate testing of all possible incarnations of #type details, fieldsets, vertical-tabs, etc, but was removed later on, because its code was not converted/updated at all, as it didn't have tests and was meant for manual testing only.)
Comment #8
markhalliwellYes, I am aware of styleguide (I have been in contact with deadarm before, https://drupal.org/sandbox/markcarver/1990728, https://bitbucket.org/markcarver/styleguide) and this is essentially what I proposed in the above IRC chat.
It does go a bit farther than that though. I also mentioned the possibility of using https://drupal.org/project/themekey to help facilitate switching the theme when viewing the documentation so the rendered example could be functional (ie: bootstrap collapsible panels, modals, popovers, etc).
There is also the possibility of parsing CSS/SCSS/LESS so that the relevant source can be linked to these components as well.
Whatever this ends up becoming, we'll definitely need to standardize it.
Oooh, just thought of this: what if themes only showed up if they provided a "THEMENAME_documentation" sub-theme? They can be hidden.
Comment #9
markhalliwellComment #10
LewisNymanI opened an issue against the style guide module to discuss adding something like this to support the Seven style guide #2125857: Support in-CSS documentation
The main problem I have against the style guide module is it is module driven, not theme driven. It's been less useful to me to display what modules think are components vs what my theme thinks are components.
Comment #11
markhalliwellYes. I agree the styleguide module needs some work (which dead_arm and I had discussed about a year ago when I created https://bitbucket.org/markcarver/styleguide from scratch).
Comment #12
markhalliwellI've created a Doodle so we can setup a time to meet in a google hangout/skype so we can discuss the logistics of how we might actually implement this/what's needed or desired: http://doodle.com/x2qfs7dk74d27cps
Comment #13
markhalliwellComment #14
dead_armI think something like dochub.io, is what is sorely needed for the theme system. If it has the components rendered like pea.rs, than that makes it even more useful. I do think that it would need to be a sub-site as opposed to a module of something embedded in core though, in order to keep it accessible and up to date.
The style guide module is useful for people to enable and test their own themes on, but does not really provide a lot in the way documentation. There's been some activity around porting Style Guide to Drupal 8, #2061293: Port Style Guide module to Drupal 8 too.
This timely ALA article came out today http://alistapart.com/article/creating-style-guides
Comment #15
markhalliwellThemeKey will likely be needed so the theme can be enabled and the proper CSS and JS is loaded. This would go a long way to help provide working "examples" of these components (ie: Bootstrap based themes have things like collapsible panels, modals, tooltips/popovers).
Style Guide module doesn't necessary need to be the one that provides the documentation per say, but it will be partially critical I think it providing a consistent way to output a "Guide", regardless if it's on a local site or public one like we're proposing.
In theory, this would also help eliminate the necessity for sites to install the styleguide module locally for published projects. Once something like this is in place (themes.d.o or w/e) we could just point them in this direction. Proprietary/internal themes would still need the module though.
Comment #16
markhalliwellHere's the link to the gdoc: http://lb.cm/m8z
Also, I added a child meta for theme documentation standards.
Comment #17
LewisNymanI've been thinking about implementation a little bit, it looks like we have three choices for every new feature we want to add:
Creating new modules is a safe option, it would make it easier to extend the capabilities of a site api.drupal.org without breaking what exists already.
It would simple to make a module that extends style guide by parsing CSS files and then including the information in the style guide module hooks
Comment #18
LewisNymanComment #19
markhalliwellComment #20
mkalkbrennerJust want to mention that the 8.x port of ThemeKey is now in progress.