FarCry reference
1 view
Skip to first unread message
Blair McKenzie
Nov 18, 2009, 7:48:12 PM11/18/09
to farcry-dev
Rob has been doing a lot of work making some under the hood FarCry stuff, like inline docs and testing, more accessible. I think you guys will find this VERY useful. I know I will.
Hey there everyone,
We've been going through a rethink on how FarCry documentation should be done. We're finding that, while there is heaps of documentation, people are having a hard time finding specific solutions. We're really proud of the documentation on http://docs.farcrycms.org/, but realise it doesn't help finding, say, what "wizardID" is on <ft:object>; what it's supposed to do, or that it is even there.
FarCry has an extensive ability to do inline documentation within the code, and we've started to try to pull that out and harness it a bit better. The goal is to get up to date, easy to grep help for FarCry as close to your code writing as possible (and searchable via google++). Additionally, we are working towards smaller, example focused bits.
We had some time allotted to us to try to get a base run of this up, and we have http://docs.farcrycore.org/ in a very, very beta state (looks horrible too). However, we'd like to get some feedback on it's content. Additionally, the CFEclipse dictionary, and the textmate bundle are generated along side the documentation so they should auto improve as the documentation improves.
Basic site usage
It should be pretty simple, but the main page has links to 6 versions of FarCry. p510 is FarCry 5.1.0 documentation, p520 is the 5.2.0 branch of FarCry (not released), and trunk is the main line development trunk (for all you bleeding edgers).
The top 3 links are documentation of the base of FarCry - Tags, Types, and Components. This is the bare core without any plugins.
The bottom 3 links are documentation of FarCry with the CMS plugin installed - Tags, Types, and Components. They are only offered as downloadable zips at this time.
To install the CFEclipse dictionary follow this post: http://blog.daemon.com.au/go/blog-post/cfeclipse-dictionaries-for-farcry-developers?objectid=44C3FCA5-13D4-B1F1-488DB716CA02CC3F Since bolt's dictionary is ... ahem ... based on CFEclipse, the dictionary might work in bolt as well, but the location of the dictionaryconfig.xml will be somewhere else.
Textmate bundle should be a double click and it's installed. In Textmate if you put your cursor over a FarCry tag, hitting ctrl+h will jump you to the entry on http://docs.farcrycore.org. To invoke the tag help type "admin:", "skin:", "sec:", etc and hit tab (without the leading '<')
Some important things to note
For the crazies
This whole thing is an automated process that happens every night against an nightly update from the repository - it should be fresh and updated as the code is updated (which should be frequently). If you want to track the process, you can follow http://twitter.com/DaemonBuilder on twitter - it will let you know if everything worked ok or if there was an error the night before.
You'll also likely notice a tweet about the unit testing. Every night the unit testing is running against the p520 branch - we still have some work on that before it's squared away, but if you're into helping with core look at fapi.cfc and fapiTest.cfc if you want to help / submit tests.
We look forward to hearing your thoughts on this
rob
Hey there everyone,
We've been going through a rethink on how FarCry documentation should be done. We're finding that, while there is heaps of documentation, people are having a hard time finding specific solutions. We're really proud of the documentation on http://docs.farcrycms.org/, but realise it doesn't help finding, say, what "wizardID" is on <ft:object>; what it's supposed to do, or that it is even there.
FarCry has an extensive ability to do inline documentation within the code, and we've started to try to pull that out and harness it a bit better. The goal is to get up to date, easy to grep help for FarCry as close to your code writing as possible (and searchable via google++). Additionally, we are working towards smaller, example focused bits.
We had some time allotted to us to try to get a base run of this up, and we have http://docs.farcrycore.org/ in a very, very beta state (looks horrible too). However, we'd like to get some feedback on it's content. Additionally, the CFEclipse dictionary, and the textmate bundle are generated along side the documentation so they should auto improve as the documentation improves.
Basic site usage
It should be pretty simple, but the main page has links to 6 versions of FarCry. p510 is FarCry 5.1.0 documentation, p520 is the 5.2.0 branch of FarCry (not released), and trunk is the main line development trunk (for all you bleeding edgers).
The top 3 links are documentation of the base of FarCry - Tags, Types, and Components. This is the bare core without any plugins.
The bottom 3 links are documentation of FarCry with the CMS plugin installed - Tags, Types, and Components. They are only offered as downloadable zips at this time.
To install the CFEclipse dictionary follow this post: http://blog.daemon.com.au/go/blog-post/cfeclipse-dictionaries-for-farcry-developers?objectid=44C3FCA5-13D4-B1F1-488DB716CA02CC3F Since bolt's dictionary is ... ahem ... based on CFEclipse, the dictionary might work in bolt as well, but the location of the dictionaryconfig.xml will be somewhere else.
Textmate bundle should be a double click and it's installed. In Textmate if you put your cursor over a FarCry tag, hitting ctrl+h will jump you to the entry on http://docs.farcrycore.org. To invoke the tag help type "admin:", "skin:", "sec:", etc and hit tab (without the leading '<')
Some important things to note
- Deprecated items are not currently being marked as such. This will happen as time allows.
- The documentation itself is a bit sparse still. We need to get more documentation actually typed into the code - patches welcome :-D
- The Components tree is all Grey because nothing is currently marked as an documented (though most of it is). See "fapi" or "fu" for a good list of things you'll likely want to know. The "scope" part of the Components is very helpful - thats where you can find the method at runtime (if it's auto created).
- We don't have any plans to back port this to earlier versions
For the crazies
This whole thing is an automated process that happens every night against an nightly update from the repository - it should be fresh and updated as the code is updated (which should be frequently). If you want to track the process, you can follow http://twitter.com/DaemonBuilder on twitter - it will let you know if everything worked ok or if there was an error the night before.
You'll also likely notice a tweet about the unit testing. Every night the unit testing is running against the p520 branch - we still have some work on that before it's squared away, but if you're into helping with core look at fapi.cfc and fapiTest.cfc if you want to help / submit tests.
We look forward to hearing your thoughts on this
rob
Marco van den Oever
Nov 18, 2009, 8:59:56 PM11/18/09
to farcry-dev
That is very awesome :) I guess now i really really have to switch
over to cfeclipse...
What do you mean by "We need to get more documentation actually typed
into the code - patches welcome", how can we help with that?
Thanks!
On Nov 19, 1:48 am, Blair McKenzie <shi...@gmail.com> wrote:
> Rob has been doing a lot of work making some under the hood FarCry stuff,
> like inline docs and testing, more accessible. I think you guys will find
> this VERY useful. I know I will.
>
> *Hey there everyone,*
>
> - Deprecated items are not currently being marked as such. This will
> happen as time allows.
> - The documentation itself is a bit sparse still. We need to get more
>
> *For the crazies*
over to cfeclipse...
What do you mean by "We need to get more documentation actually typed
into the code - patches welcome", how can we help with that?
Thanks!
On Nov 19, 1:48 am, Blair McKenzie <shi...@gmail.com> wrote:
> Rob has been doing a lot of work making some under the hood FarCry stuff,
> like inline docs and testing, more accessible. I think you guys will find
> this VERY useful. I know I will.
>
>
> We've been going through a rethink on how FarCry documentation should be
> done. We're finding that, while there is heaps of documentation, people are
> having a hard time finding specific solutions. We're really proud of the
> documentation onhttp://docs.farcrycms.org/, but realise it doesn't help
> We've been going through a rethink on how FarCry documentation should be
> done. We're finding that, while there is heaps of documentation, people are
> having a hard time finding specific solutions. We're really proud of the
> finding, say, what "wizardID" is on <ft:object>; what it's supposed to do,
> or that it is even there.
>
> FarCry has an extensive ability to do inline documentation within the code,
> and we've started to try to pull that out and harness it a bit better. The
> goal is to get up to date, easy to grep help for FarCry as close to your
> code writing as possible (and searchable via google++). Additionally, we
> are working towards smaller, example focused bits.
>
> We had some time allotted to us to try to get a base run of this up, and we
> havehttp://docs.farcrycore.org/in a very, very beta state (looks horrible
> or that it is even there.
>
> FarCry has an extensive ability to do inline documentation within the code,
> and we've started to try to pull that out and harness it a bit better. The
> goal is to get up to date, easy to grep help for FarCry as close to your
> code writing as possible (and searchable via google++). Additionally, we
> are working towards smaller, example focused bits.
>
> We had some time allotted to us to try to get a base run of this up, and we
> too). However, we'd like to get some feedback on it's content.
> Additionally, the CFEclipse dictionary, and the textmate bundle are
> generated along side the documentation so they should auto improve as the
> documentation improves.
>
> *Basic site usage*
> Additionally, the CFEclipse dictionary, and the textmate bundle are
> generated along side the documentation so they should auto improve as the
> documentation improves.
>
>
> It should be pretty simple, but the main page has links to 6 versions of
> FarCry. p510 is FarCry 5.1.0 documentation, p520 is the 5.2.0 branch of
> FarCry (not released), and trunk is the main line development trunk (for all
> you bleeding edgers).
>
> The top 3 links are documentation of the base of FarCry - Tags, Types, and
> Components. This is the bare core without any plugins.
>
> The bottom 3 links are documentation of FarCry with the CMS plugin installed
> - Tags, Types, and Components. They are only offered as downloadable zips
> at this time.
>
> To install the CFEclipse dictionary follow this post:http://blog.daemon.com.au/go/blog-post/cfeclipse-dictionaries-for-far...
> It should be pretty simple, but the main page has links to 6 versions of
> FarCry. p510 is FarCry 5.1.0 documentation, p520 is the 5.2.0 branch of
> FarCry (not released), and trunk is the main line development trunk (for all
> you bleeding edgers).
>
> The top 3 links are documentation of the base of FarCry - Tags, Types, and
> Components. This is the bare core without any plugins.
>
> The bottom 3 links are documentation of FarCry with the CMS plugin installed
> - Tags, Types, and Components. They are only offered as downloadable zips
> at this time.
>
> Since bolt's dictionary is ... ahem ... based on CFEclipse, the
> dictionary
> might work in bolt as well, but the location of the dictionaryconfig.xml
> will be somewhere else.
>
> Textmate bundle should be a double click and it's installed. In Textmate if
> you put your cursor over a FarCry tag, hitting ctrl+h will jump you to the
> entry onhttp://docs.farcrycore.org. To invoke the tag help type "admin:",
> dictionary
> might work in bolt as well, but the location of the dictionaryconfig.xml
> will be somewhere else.
>
> Textmate bundle should be a double click and it's installed. In Textmate if
> you put your cursor over a FarCry tag, hitting ctrl+h will jump you to the
> "skin:", "sec:", etc and hit tab (without the leading '<')
>
> *Some important things to note*
>
>
> - Deprecated items are not currently being marked as such. This will
> happen as time allows.
> - The documentation itself is a bit sparse still. We need to get more
> documentation actually typed into the code - patches welcome :-D
> - The Components tree is all Grey because nothing is currently marked as
> an documented (though most of it is). See "fapi" or "fu" for a good list of
> things you'll likely want to know. The "scope" part of the Components is
> very helpful - thats where you can find the method at runtime (if it's auto
> created).
> - We don't have any plans to back port this to earlier versions
> things you'll likely want to know. The "scope" part of the Components is
> very helpful - thats where you can find the method at runtime (if it's auto
> created).
>
> *For the crazies*
>
> This whole thing is an automated process that happens every night against an
> nightly update from the repository - it should be fresh and updated as the
> code is updated (which should be frequently). If you want to track the
> process, you can followhttp://twitter.com/DaemonBuilderon twitter - it
> This whole thing is an automated process that happens every night against an
> nightly update from the repository - it should be fresh and updated as the
> code is updated (which should be frequently). If you want to track the
Blair McKenzie
Nov 18, 2009, 9:13:06 PM11/18/09
to farcr...@googlegroups.com
Documentation is included in the code. See http://docs.farcrycms.org/display/FCCORE/Auto-Documentation. It makes it easier to maintain and version documentation because examples and notes are right there beside the code. The above wiki doesn't mention it, but much of the same stuff is supported for content types / rules / forms.
If anyone feels they can add something to the documentation - a code snippet, missing attribute descriptions, or some extra information about a deprecated function - create a ticket with the updated file and notify us. The day after we commit the changes they will appear in the online documentation. Automatically. (Rob is awesome).
Blair
If anyone feels they can add something to the documentation - a code snippet, missing attribute descriptions, or some extra information about a deprecated function - create a ticket with the updated file and notify us. The day after we commit the changes they will appear in the online documentation. Automatically. (Rob is awesome).
Blair
--
You received this message cos you are subscribed to "farcry-dev" Google group.
To post, email: farcr...@googlegroups.com
To unsubscribe, email: farcry-dev+...@googlegroups.com
For more options: http://groups.google.com/group/farcry-dev
--------------------------------
Follow us on Twitter: http://twitter.com/farcry
Marco van den Oever
Nov 21, 2009, 3:04:22 PM11/21/09
to farcry-dev
Coowl, installed eclipse / cfeclipse / docs, now checking how it all
works....
Thanks.
On Nov 19, 3:13 am, Blair McKenzie <shi...@gmail.com> wrote:
> Documentation is included in the code. Seehttp://docs.farcrycms.org/display/FCCORE/Auto-Documentation. It makes it
> > > havehttp://docs.farcrycore.org/ina very, very beta state (looks
> > > process, you can followhttp://twitter.com/DaemonBuilderontwitter - it
works....
Thanks.
On Nov 19, 3:13 am, Blair McKenzie <shi...@gmail.com> wrote:
> Documentation is included in the code. Seehttp://docs.farcrycms.org/display/FCCORE/Auto-Documentation. It makes it
> easier to maintain and version documentation because examples and notes are
> right there beside the code. The above wiki doesn't mention it, but much of
> the same stuff is supported for content types / rules / forms.
>
> If anyone feels they can add something to the documentation - a code
> snippet, missing attribute descriptions, or some extra information about a
> deprecated function - create a ticket with the updated file and notify us.
> The day after we commit the changes they will appear in the online
> documentation. Automatically. (Rob is awesome).
>
> Blair
>
> On Thu, Nov 19, 2009 at 12:59 PM, Marco van den Oever <
>
> right there beside the code. The above wiki doesn't mention it, but much of
> the same stuff is supported for content types / rules / forms.
>
> If anyone feels they can add something to the documentation - a code
> snippet, missing attribute descriptions, or some extra information about a
> deprecated function - create a ticket with the updated file and notify us.
> The day after we commit the changes they will appear in the online
> documentation. Automatically. (Rob is awesome).
>
> Blair
>
> On Thu, Nov 19, 2009 at 12:59 PM, Marco van den Oever <
>
> > > will let you know if everything worked ok or if there was an error the
> > night
> > > before.
>
> > > You'll also likely notice a tweet about the unit testing. Every night
> > the
> > > unit testing is running against the p520 branch - we still have some work
> > on
> > > that before it's squared away, but if you're into helping with core look
> > at
> > > fapi.cfc and fapiTest.cfc if you want to help / submit tests.
>
> > > We look forward to hearing your thoughts on this
>
> > > rob
>
> > --
> > You received this message cos you are subscribed to "farcry-dev" Google
> > group.
> > To post, email: farcr...@googlegroups.com
> > To unsubscribe, email: farcry-dev+...@googlegroups.com<farcry-dev%2Bunsu...@googlegroups.com>
> > night
> > > before.
>
> > > You'll also likely notice a tweet about the unit testing. Every night
> > the
> > > unit testing is running against the p520 branch - we still have some work
> > on
> > > that before it's squared away, but if you're into helping with core look
> > at
> > > fapi.cfc and fapiTest.cfc if you want to help / submit tests.
>
> > > We look forward to hearing your thoughts on this
>
> > > rob
>
> > --
> > You received this message cos you are subscribed to "farcry-dev" Google
> > group.
> > To post, email: farcr...@googlegroups.com
Marco van den Oever
Nov 21, 2009, 5:05:34 PM11/21/09
to farcry-dev
Hallelujah praise the ... euhmm and Rob too!
I thought switching over was hard but it seems pretty easy, this is
really awesome, normally browse and search for docs, now while coding
have it all in sight... wonder how fast development goes now :)
On Nov 21, 9:04 pm, Marco van den Oever <marcovandenoe...@gmail.com>
> > > > havehttp://docs.farcrycore.org/inavery, very beta state (looks
> > > > process, you can followhttp://twitter.com/DaemonBuilderontwitter- it
I thought switching over was hard but it seems pretty easy, this is
really awesome, normally browse and search for docs, now while coding
have it all in sight... wonder how fast development goes now :)
On Nov 21, 9:04 pm, Marco van den Oever <marcovandenoe...@gmail.com>
Rob Rohan
Nov 21, 2009, 5:38:36 PM11/21/09
to farcr...@googlegroups.com
:-D Blair did the heavy lifting on this - don't let him fool you. He
wrote the documentation plugin that exports all the information from
a running FarCry instance, and setup the FarCry test servers. The
documentation plugin is quite cool on it's own to browse the code and
get more information about content types and webskin. I just wrote a
few XSLT and make files, but thank you for the nice comment we totally
appreciate it.
Let us know how we can improve it ^_^
Rob Rohan (小罗)
http://robrohan.com
http://twitter.com/robrohan
wrote the documentation plugin that exports all the information from
a running FarCry instance, and setup the FarCry test servers. The
documentation plugin is quite cool on it's own to browse the code and
get more information about content types and webskin. I just wrote a
few XSLT and make files, but thank you for the nice comment we totally
appreciate it.
Let us know how we can improve it ^_^
Rob Rohan (小罗)
http://robrohan.com
http://twitter.com/robrohan
Marco van den Oever
Nov 23, 2009, 7:11:14 AM11/23/09
to farcry-dev
Coowl, thank you all! Will use and check for further improvements.
Reply all
Reply to author
Forward
0 new messages