What is not ready yet is an actual online repository to start sharing code. We plan to add this functionality to the fantom.org web site in the coming months. Although the technology is deployed in our commercial business and is getting some good field testing :-)
New Doc Infrastructure
Related to the fanr changes, is a completely redesigned documentation infrastructure which includes:
new file formats for docs distributed in pods
completely rewritten compilerDoc (replaces old docCompiler)
clean DOM for documentation loaded straight from pod zips (no more reflection)
reusable renderers for type, chapter, indexing HTML generation
reusable syntax modeling and HTML renderer for different programming languages
Since the new design lets us cleanly generate docs from pod without reflection, we now have more flexibility for building fanr documentation servers. When we add community fanr support to fantom.org, everybody's docs will be published with nice cross-linking and a centralized search engine.
With the new documentation engine, we decided to stop shipping HTML docs in the distribution since they consumed about a 1/3 of the total size. Instead you can now easily generate offline docs once you have new build installed using this command:
fan compilerDoc -all
The local docs are un-themed and will also let you easily re-doc any local pods you might also have.
As part of this new design, you will notice some differences in the docs:
top level index is more compressed
manual/chapter TOC navigation is much nicer for quick linking
pod-doc is now included in the pod index itself
source files are now by file instead of by type (avoiding dups)
Flux Syntax Changes
Part of the new doc rework, we pulled the syntax configuration files out of fluxText into a new reusable syntax pod. The configuration files themselves remain the same, but if you are a Flux user be aware of these changes:
syntax file now live in "etc/syntax/" instead of "etc/fluxText/syntax"
mapping of extensions to syntax files is done in "etc/syntax/ext.props"
syntax color coding is now configured in TextEditorOptions
The new API is easy to use if you want to generate syntax color coded HTML from any of the languages we support. See the new syntax docs.
API Enhancments
A couple of nice new API features to note:
Lots of fwt-js enhancements for keyboard and focus support
#1617: Map.get returns default value for existing key if value is null
lbertrandSat 3 Sep 2011
I tried to generate the documentation and have seen some errors. See below.
C:\DEV\FANTOM\fantom-1.0.60>fan compilerDoc -all
hello::/doc/Main.apidoc: Cannot parse sys::Err: Expected == <name>
compilerDoc::ApiDocParser.parseType (ApiDocParser.fan:61)
compilerDoc::ApiDocParser.parseType (ApiDocParser.fan)
compilerDoc::DocPod.load (DocPod.fan:140)
fan.sys.Func$Indirect1.call (Func.java:145)
fan.sys.Map.each (Map.java:339)
compilerDoc::DocPod.load (DocPod.fan:123)
compilerDoc::DocPod.isManual (DocPod.fan:305)
compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:201)
fan.sys.List.each (List.java:528)
compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:199)
compilerDoc::FileDocWriter.write (FileDocWriter.fan:49)
compilerDoc::Main.run (Main.fan:49)
util::AbstractMain.main (AbstractMain.fan:370)
java.lang.reflect.Method.invoke (Unknown)
fan.sys.Method.invoke (Method.java:558)
fan.sys.Method$MethodFunc.callOn (Method.java:230)
fan.sys.Method.callOn (Method.java:139)
fanx.tools.Fan.callMain (Fan.java:171)
fanx.tools.Fan.executeType (Fan.java:136)
fanx.tools.Fan.execute (Fan.java:41)
1 More...
helloModularity::/doc/Main.apidoc: Cannot parse sys::Err: Expected == <name>
compilerDoc::ApiDocParser.parseType (ApiDocParser.fan:61)
compilerDoc::ApiDocParser.parseType (ApiDocParser.fan)
compilerDoc::DocPod.load (DocPod.fan:140)
fan.sys.Func$Indirect1.call (Func.java:145)
fan.sys.Map.each (Map.java:339)
compilerDoc::DocPod.load (DocPod.fan:123)
compilerDoc::DocPod.isManual (DocPod.fan:305)
compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:201)
fan.sys.List.each (List.java:528)
compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:199)
compilerDoc::FileDocWriter.write (FileDocWriter.fan:49)
compilerDoc::Main.run (Main.fan:49)
util::AbstractMain.main (AbstractMain.fan:370)
java.lang.reflect.Method.invoke (Unknown)
fan.sys.Method.invoke (Method.java:558)
fan.sys.Method$MethodFunc.callOn (Method.java:230)
fan.sys.Method.callOn (Method.java:139)
fanx.tools.Fan.callMain (Fan.java:171)
fanx.tools.Fan.executeType (Fan.java:136)
fanx.tools.Fan.execute (Fan.java:41)
1 More...
modularity::/doc/Modularity.apidoc: Cannot parse sys::Err: Expected == <name>
compilerDoc::ApiDocParser.parseType (ApiDocParser.fan:61)
compilerDoc::ApiDocParser.parseType (ApiDocParser.fan)
compilerDoc::DocPod.load (DocPod.fan:140)
fan.sys.Func$Indirect1.call (Func.java:145)
fan.sys.Map.each (Map.java:339)
compilerDoc::DocPod.load (DocPod.fan:123)
compilerDoc::DocPod.isManual (DocPod.fan:305)
compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:201)
fan.sys.List.each (List.java:528)
compilerDoc::FileDocWriter.writeIndex (FileDocWriter.fan:199)
compilerDoc::FileDocWriter.write (FileDocWriter.fan:49)
compilerDoc::Main.run (Main.fan:49)
util::AbstractMain.main (AbstractMain.fan:370)
java.lang.reflect.Method.invoke (Unknown)
fan.sys.Method.invoke (Method.java:558)
fan.sys.Method$MethodFunc.callOn (Method.java:230)
fan.sys.Method.callOn (Method.java:139)
fanx.tools.Fan.callMain (Fan.java:171)
fanx.tools.Fan.executeType (Fan.java:136)
fanx.tools.Fan.execute (Fan.java:41)
1 More...
Writing pod 'build' ...
Writing pod 'compiler' ...
Writing pod 'compilerDoc' ...
Writing pod 'compilerJava' ...
Writing pod 'compilerJs' ...
Writing pod 'concurrent' ...
Writing pod 'docFanr' ...
Writing pod 'docIntro' ...
Writing pod 'docLang' ...
Writing pod 'docTools' ...
Writing pod 'dom' ...
Writing pod 'email' ...
Writing pod 'fandoc' ...
Writing pod 'fanr' ...
Writing pod 'fansh' ...
Writing pod 'flux' ...
Writing pod 'fluxText' ...
Writing pod 'fwt' ...
Writing pod 'gfx' ...
Writing pod 'hello' ...
Writing pod 'helloModularity' ...
Writing pod 'inet' ...
Writing pod 'modularity' ...
Writing pod 'obix' ...
Writing pod 'sql' ...
Writing pod 'syntax' ...
Writing pod 'sys' ...
Writing pod 'util' ...
Writing pod 'web' ...
Writing pod 'webmod' ...
Writing pod 'wisp' ...
Writing pod 'xml' .. .
Also, the doc directory is created under the user's work environment - Should it not be inside the fan main environment where the distribution is installed?
brianSat 3 Sep 2011
You will need to recompile all your modules.
Yeah, should be no problem to switch default to working env. Good idea. In meantime you can just specify -outDir on command line to say where you want it.
lbertrandSat 3 Sep 2011
What do you mean by recompoiling all the modules?
I just took the distribution from the website, unzipped it and ran the fan compilerDoc -all command.
I tried again but I had the same errors - is it a problem with the 1.0.60 distribution?
andySat 3 Sep 2011
Your installation is picking up some non-dist pods (hello, helloModularity, modularity) - since the docapi format changed with how docs are stored inside pods - those pods will need to get rebuilt for fan compilerDoc to work on them. Or just nuke them out of your lib/fan dir if not needed.
lbertrandSat 3 Sep 2011
Ok, understood - these pods are some test pods I made a while back... Just need to build them again.
But this leads me to wonder about how this works. I was thinking that it will only build the documentation of the core Fantom distro, and not mix the documentation with my own pods... I think that by default documentation of each pod should be built where it is - so there are no mix up between core distro and own users pod...
jessevdamSun 4 Sep 2011
The sources of the compiler pod are nicely grouped in different folders, it would nice that the doc also would hold this same grouping of the classes.
peterMon 5 Sep 2011
Thanks for all the work on the new build. It would help to have a readme in the download folder, especially now docs are not included, to help newcomers get started.
The new documentation system is more convenient for offline browsing, as the non doc headings are not present. But links to examples are not working for me, a protocol error, they worked in the earlier version.
brian Thu 1 Sep 2011
The latest build has been posted for download and online docs updated.
This build sports two huge new features: fanr and new doc infrastructure.
Fanr
All the code and tools for Fantom repositories are now available in this build. This includes:
fanrcommand line for querying, installing from, and publishing to reposWhat is not ready yet is an actual online repository to start sharing code. We plan to add this functionality to the fantom.org web site in the coming months. Although the technology is deployed in our commercial business and is getting some good field testing :-)
New Doc Infrastructure
Related to the fanr changes, is a completely redesigned documentation infrastructure which includes:
Since the new design lets us cleanly generate docs from pod without reflection, we now have more flexibility for building fanr documentation servers. When we add community fanr support to fantom.org, everybody's docs will be published with nice cross-linking and a centralized search engine.
With the new documentation engine, we decided to stop shipping HTML docs in the distribution since they consumed about a 1/3 of the total size. Instead you can now easily generate offline docs once you have new build installed using this command:
The local docs are un-themed and will also let you easily re-doc any local pods you might also have.
As part of this new design, you will notice some differences in the docs:
Flux Syntax Changes
Part of the new doc rework, we pulled the syntax configuration files out of
fluxTextinto a new reusablesyntaxpod. The configuration files themselves remain the same, but if you are a Flux user be aware of these changes:The new API is easy to use if you want to generate syntax color coded HTML from any of the languages we support. See the new syntax docs.
API Enhancments
A couple of nice new API features to note:
Change Log
Build 1.0.60 (1 Sept 2011)
doctarget from build scriptslbertrand Sat 3 Sep 2011
I tried to generate the documentation and have seen some errors. See below.
Also, the doc directory is created under the user's work environment - Should it not be inside the fan main environment where the distribution is installed?
brian Sat 3 Sep 2011
You will need to recompile all your modules.
Yeah, should be no problem to switch default to working env. Good idea. In meantime you can just specify -outDir on command line to say where you want it.
lbertrand Sat 3 Sep 2011
What do you mean by recompoiling all the modules?
I just took the distribution from the website, unzipped it and ran the
fan compilerDoc -allcommand.I tried again but I had the same errors - is it a problem with the 1.0.60 distribution?
andy Sat 3 Sep 2011
Your installation is picking up some non-dist pods (hello, helloModularity, modularity) - since the docapi format changed with how docs are stored inside pods - those pods will need to get rebuilt for
fan compilerDocto work on them. Or just nuke them out of yourlib/fandir if not needed.lbertrand Sat 3 Sep 2011
Ok, understood - these pods are some test pods I made a while back... Just need to build them again.
But this leads me to wonder about how this works. I was thinking that it will only build the documentation of the core Fantom distro, and not mix the documentation with my own pods... I think that by default documentation of each pod should be built where it is - so there are no mix up between core distro and own users pod...
jessevdam Sun 4 Sep 2011
The sources of the compiler pod are nicely grouped in different folders, it would nice that the doc also would hold this same grouping of the classes.
peter Mon 5 Sep 2011
Thanks for all the work on the new build. It would help to have a readme in the download folder, especially now docs are not included, to help newcomers get started.
The new documentation system is more convenient for offline browsing, as the non doc headings are not present. But links to examples are not working for me, a protocol error, they worked in the earlier version.