Permalink
Browse files

tweaking READMEs and yard config

  • Loading branch information...
1 parent 7089415 commit 3c32a1f81edda1a7d4a6f20e6f7ea6258cfd60dc @ethn ethn committed Aug 5, 2015
View
Oops, something went wrong.
View
Binary file not shown.
Binary file not shown.
View
@@ -1,9 +1,9 @@
-card/lib/**/*.rb \
-wagn/lib/**/*.rb \
+card/**/lib/**/*.rb \
+wagn/**/lib/**/*.rb \
wagn/rails/**/*.rb \
decko-rails/lib/**/*.rb \
../sites/core-dev/tmp/set*/**/*.rb - \
-*.rdoc \
+**/*.rdoc \
card/GPL \
card/LICENSE \
card/VERSION
@@ -1,61 +0,0 @@
-==Is this doc for you?
-
-This page offers a Developer's introduction to the Wagn code base and how to customize it for your own needs. it assumes you're a ruby developer or, at least, someone who does not fear ruby code.
-
-It also assumes that you've experimented with Wagn enough to have some familiarity with the basics (cards, types, rules, etc.) <b>If you have no idea what a card is, you may find it helpful to begin at {http://wagn.org Wagn.org}</b> to get a sense of what Wagn's all about.
-
-And, finally, it assumes you're looking at it from a docs site (ie, NOT GitHub). The page is peppered with links; if they're breaking, try FIXME - (give links here).
-
-
-==Intro
-
-If you're new to Wagn development, you may be trying to wrap your head around <b>whether Wagn is an application or a development framework. It's both.</b>
-
-When you install a new Wagn, you get a lot more out of the box than you would with a typical dev framework; you have a working website right away. We often call Wagn sites "decks" (as in groups of cards.) After seeding your deck (with `wagn seed`), you will have lots of things built in: account handling, edit histories, default layouts, CSS, etc. In other words: you have a basic application.
-
-But a newly seeded deck is just a starting point. <b>Wagn is a development framework in which you start <i>in the middle of things</i> rather than from scratch</b>. Seeding is a bit of a headstart, and it means that designers, developers, and content creators can start working in parallel on day 1. But the seeded cards don't determine what you can build with Wagn; you can add things, you can remove things... In fact, we want to make it possible to build pretty much whatever you want.
-
-
-==Ruby on Rails Descendant
-
-It's likely that many folks reading this are Ruby-on-Rails developers. Wagn owes a great deal of debt to the Rails community, both in terms of code and in stylistic guidance. Rails developers will find lots of familiar patterns in Wagn, but we should be clear: <b>Wagn development is different</b>.
-
-Typical Rails development will involve creating lots of new models, views, and controllers. Wagn mod developers do create lots of views (though they're quite different from Rails views), but we never create new models or controllers. In the Wagn gem there is one controller ({CardController}), one main model ({Card}), and several other models to optimize the Card model and track its history ({Card::Reference}, {Card::Act}, {Card::Action}, and {Card::Change}).
-
-Most Wagn developers never have to give the controller or any model besides Card any thought. The equivalent of creating a new model is configuring a new Set of cards. The equivalent of creating new actions on controllers is creating new events that are conditionally triggeres for a Set of cards.
-
-So, as a starting place it's probably <b>best to think of Wagn not as a Rails app but a Rails descendant</b>. Rails development experience is definitely a plus in getting to know Wagn, but Wagn offers a new architecture, and lot of new possibilities.
-
-
-==MoFoS Architecture
-
-Wagn is not, like Rails, an implementation of the "MVC" (Model-View-Controller) architectural pattern, or any well-established pattern, really. Instead, we like to think that we're the first instance of a new pattern that we call _MoFoS_.
-
-MoFoS stands for "Model-Formats-Sets". It's intentional that the word "Model" alone is singular; the idea is that there is just one primary data model (Card, in Wagn's case), and that this model is given meaning by subdividing into multiple configurable Sets and made productive by connecting cards to multiplfe Formats.
-
-_Sets_ are a central organizing concept for both Wagneers and Wagn developers. If you've edited Rules through a card toolbar in any Wagn deck, you will have encountered Sets. For example, imagine you're on a User card named "Henry Tai", and you decide to edit its structure. When you edit its rule, you will be prompted to choose the Set of cards to which the rule applies, eg:
-
-* Just "Henry Tai"
-* All Users
-* All Cards
-
-Depending on which Set you choose, the Rule in question will be applied to a specific group of cards. This same general pattern occurs in Wagn code: <b>code rules (methods) are organized under the Set of cards to which they apply.</b>
-
-The great power of MoFoS is that, unlike in MVC, code rules (and data rules) can be as narrow or specific as desired. In MVC, it's challenging to create rules that apply to multiple models or single instances of a model; in MoFoS, this is very fluid.
-
-
-==Mods
-
-A Wagn Mod is a discrete piece of Wagn functionality
-
-chunk format layout set set_pattern spec file lib
-
-===Set Patterns
-
-===Formats
-If there are rules on multiple sets of which a given card is a member, then precedence is determined by Set Pattern. For example, the above three sets have the Self pattern (always a single card), the Type pattern (here "User"), and the All pattern. Set Patterns have a fixed override order, beginning with a specific model instance and ending with the Set of all cards.
-
-While Set Patterns have a clean hierarchy, sets themselves do not. This means traditional class hierarchies do not suffice for representing Set code. A Wagn example: Say A+address is a "Phrase" card and B+address is a "Basic" card. This implies that the Set of "cards ending in +address" cannot safely inherit rules from any given type Set.
-
-This organizing concept turns out to be remarkably
-
View
@@ -1,108 +0,0 @@
-=Wagn: how pioneers roll
-
-==Basics
-
-Wagn is serious web development made fun.
-
-"Wagneers" have used Wagn to create open community sites, private knowledge management sites, public proposal submission sites with private back-ends for review, project management systems, wikis, blogs, journals, forums, and more.
-
-Install Wagn, open a webpage, and get started. With Wagn's wiki-inspired building blocks, you can collaborate from day one on content, design, and structure create elegant web systems on the fly. And ruby developers can take these creations even further with Wagn's development framework. Wagn's innovative Mods API supports boundless creativity while integrating seamlessly with structures created on the site.
-
-FIXME - add cldstr link
-
-
-==System Requirements
-
-Ruby[http://www.ruby-lang.org/en/]:: version 1.8.7 or higher
-Bundler[http://gembundler.com/]:: version 1.0 or higher
-ImageMagick[http://www.imagemagick.org/]::
-A database engine:: Either MySQL[http://www.mysql.com/] or PostgreSQL[http://www.postgresql.org/]
-Node.js[https://nodejs.org/]:: or another {JavaScript runtime}[https://github.com/sstephenson/execjs]
-
-==Installation
-
-===1. install the gem
-
- gem install wagn
-
-Watch carefully for errors!
-
-
-===2. create a new wagn application
-
- wagn new mysite
-
-
-===3. create / seed database
-
-Edit the config/database.yml file as necessary. More about database configuration at http://www.wagn.org/database_configuration.
-
-Then run
-
- cd mysite
- wagn seed
-
-..to create and seed the database
-
-
-===4. start your server
-
-To fire up the default, built-in WEBrick server, just run:
-
- wagn server
-
-...and point your browser to http://localhost:3000 (unless otherwise configured).
-
-WEBrick is great for a quick test run. To run a production website, see http://www.wagn.org/wagn_in_production.
-
-
-==Upgrading
-
-===Standard Upgrades
-
-====1. Backups
-Always back up your database and uploaded files.
-
-====2. Update Libraries
-
-From your wagn root directory run:
-
- bundle update
-
-====3. Update Database
-
-Run the following:
-
- wagn update
-
-====4. Restart your server.
-
-===Upgrading pre-gem Wagn sites
-
-First check the Wagn version of your existing site.
-
-====Version 1.10 or newer
-
-1. Create a new Wagn app using steps 1 and 2 from the installation section above.
-2. Copy config/database.yml from the old site to the new one.
-3. Copy the old local/files contents to the new "files" directory.
-4. If you have edited wagn.yml in your old site, make the corresponding changes to the new config/application.rb file.
-5. Follow the standard upgrade procedure above.
-
-====Older than Version 1.10
-
-First update your Wagn to version 1.10 via the old update mechanisms, and then follow the directions above.
-
-
-==Developing
-
-Wagn allows for deep collaboration and integration between "wagneers" (who organize data via a wagn site) and software developers.
-
-Learn more at "GETTING STARTED - Developers"
-FIXME - link
-
-
-
-==More Resources
-
-Find lots more info at http://wagn.org
View
@@ -0,0 +1,94 @@
+
+=A Developer's introduction to the Wagn/Card code base
+
+Start here before you dig into the code.
+
+==Intro
+
+===Am I in the right place?
+
+This page assumes:
+
+* You're a ruby developer or, at least, someone who does not fear ruby code. <b>Not a techie? Try {http://wagn.org Wagn.org}</b>
+* You've experimented with Wagn enough to know the basics (cards, types, rules, etc.) <b>No idea what a card is? Try {http://wagn.org Wagn.org}</b>.
+* You're looking at this page from a docs site (ie, NOT GitHub) so you can use our links to navigate code. <b>Links look funny? Try {http://rubydoc.info/gems/card/README_Developers.rdoc our page at rubydocs.info}.</b>
+
+
+===Is Wagn an application or a development framework?
+
+It's both.
+
+When you install a new Wagn, you have a working "deck" right away. There are lots of things built in: account handling, edit histories, default layouts, CSS, etc. In other words: you have a basic application.
+
+But a newly seeded deck is just a starting point. <b>Wagn is a development framework in which you start <i>in the middle of things</i> rather than from scratch</b>. Seeding is a bit of a headstart, and it means that designers, developers, and content creators can start working in parallel on day 1. But the seeded cards don't determine what you can build with Wagn; you can add things, you can remove things... In fact, we want to make it possible to build pretty much whatever you want.
+
+===Sets
+
+_Sets_ are a central organizing concept for both Wagneers and Wagn developers.
+
+If you've edited Rules through a card toolbar in any Wagn deck, you will have encountered Sets. For example, imagine you're on a User card named "Henry Tai", and you decide to edit its structure. When you edit its rule, you will be prompted to choose the Set of cards to which the rule applies, eg:
+
+* Just "Henry Tai"
+* All Users
+* All Cards
+
+Depending on which Set you choose, the Rule in question will be applied to a specific group of cards. This same general pattern occurs in Wagn code: <b>code rules (methods) are organized under the Set of cards to which they apply.</b>
+
+
+===MoFoS Architecture
+
+Sets are central to Wagn's architecture. Wagn is not, like Rails, an implementation of the "MVC" (Model-View-Controller) architectural pattern. Instead, we like to think that we're the first instance of a new pattern that we call _MoFoS_.
+
+MoFoS stands for "Model-Formats-Sets": One Model, viewable in many Formats, divisible into Sets.
+
+The great power of MoFoS is that, thanks to Sets, code rules (and data rules) can be as narrow or specific as desired.
+
+
+===Is Wagn Ruby on Rails?
+
+It's likely that many folks reading this are Ruby-on-Rails developers. They'll find lots of familiar patterns in Wagn, but we should be clear: <b>Wagn is a Rails descendant and owes a ton to the Rails community, but Wagn is not Rails</b>.
+
+The main difference is that while Rails' core pattern is creating new things (especially models, views, and controllers), Wagn's core pattern is subdividing exising things into new Sets.
+
+Wagn mod developers do create lots of views (though they're quite different from Rails views), but we never create new models or controllers. In the Wagn gem there is one controller ({CardController}), one main model ({Card}), and several other models to optimize the Card model and track its history ({Card::Reference}, {Card::Act}, {Card::Action}, and {Card::Change}).
+
+Wagn's equivalent of creating a new model is configuring a new Set of cards. Its equivalent of creating new actions on controllers is creating new events that are conditionally triggeres for a Set of cards.
+
+Rails development experience is definitely a plus in getting to know Wagn, but Wagn offers a new architecture, and lot of new possibilities.
+
+
+==Mods
+
+A Wagn Mod is a discrete piece of Wagn functionality. If you want to customize a Wagn deck in a way that can't be done on the site itself, odds are you want a mod.
+
+The most convenient way to add a mod is in the `mod` directory of your deck, eg:
+
+ /mydeck/mod/mymod
+
+A mod can have several different directories: <i>chunk, format, layout, set, set_pattern, spec, file, and lib</i>. Of these, the set directory is by far the most important.
+
+===Creating a mod with set modules
+
+Set modules are defined in a mod's set directory, eg:
+
+ /mydeck/mod/mymod/set/
+
+For example, if your deck has Company cards, you can extend the behavior of those cards by adding a set module like so:
+
+ /mydeck/mod/mymod/type/company.rb
+
+Note that "company" here does not refer to its "name", but rather its "codename" (which an administrator might add to the Company card via the RESTful web API with a url like
+
+ /update/Company?card[codename]=company
+
+Generally speaking, code should never refer to a card by name; otherwise it will break when the card is renamed. Instead, it should use the codename, which will continue to work even if the canonical name is changed.
+
+
+The full path of a set module follows this pattern
+
+ (mod dir)/set/set_pattern(/anchor)(/additional).rb
+
+==....more coming soon!
+
+
+
View
@@ -10,10 +10,9 @@
a. how ruby Card objects work and
b. how to extend them.
-It assumes that you've already read the introductory text in {file:GETTING STARTED - Developers.rdoc}.
+It assumes that you've already read the introductory text in {file:README_Developers.rdoc}.
=end
-
class Card < ActiveRecord::Base
# attributes that ActiveJob can handle

0 comments on commit 3c32a1f

Please sign in to comment.