Hi Chris,
It is trivial to write a 'Writer' that writes the contents of the
Abstract Syntax Tree to a database or REST interface, so that is
definitely an option.
I recommend using a Writer instead of replacing the serialization
process as it will help gain performance and benefit from
'behaviours'; that augment the object graph 'just in time'.
I am afraid I have to disappoint you with regards to the XML; it is
deprecated and will be replaced with a serialized object graph with
the next release.
For compatibility reasons I am writing a compatibility layer but that
will be removed with version 2.1.
I'd like to point out, to provide a few options and insights, that
phpDocumentor2 is also capable of augmenting the Object Graph using
Behaviours (which are executed right before the transformation to
HTML).
I am looking forward to your, and the other collaborator's input.
Mike
On 27.02.2013 01:06, Chris Davenport wrote:
> Hi Mike,
>
> My current thinking, obviously subject to change in the light of our
> conversations here, is that we would use a code analysis tool like
> phpDocumentor to generate a representation of the code that can be
> stored in a database (maybe from the XML that phpDocumentor
> generates?). This data can then be augmented from other data sources
> such as Github, JoomlaCode, unit test results, other code analysis
> tools, etc.
>
> We can then build a variety of applications to query and extract data
> from that database. Obviously, the traditional documentation website
> (like
api.joomla.org [4]) can be created with PHP-generated pages
> instead of the current static HTML ones and we would have the full
> power of Joomlas templating system available to make that look really
> cool. Although that could be built as a traditional Joomla
> component, it would be interesting to consider first building a set
> of
> RESTful web services, then building an application or component that
> would use those services to build the web pages. Im thinking that
> parts of the pages could be pulled in with Ajax calls rather than
> having entire pages being rendered server-side, but thats something
> we
> can experiment with.
>
> Commenting would be quite straightforward since Joomla could easily
> support that. Integration with IDEs and other external tools would
> also be straightforward given that the data would be accessible using
> a REST interface.
>
> Im sure ElasticSearch or some other standalone search engine would be
> great, but Id prefer not to have to depend on external tools to
> support the search if possible because I have it in mind that
> whatever
> we develop will be made available to third-party extension developers
> to document their code and some of them might not be in a position to
> install such software on their servers. Consequently I was thinking
> of using Joomlas own Smart Search for that purpose. No reason why
> Smart Search should not be given a REST interface too.
>
> Thinking about it, if the data can be accessed via RESTful web
> services, then it would make sense to look at having phpDocumentors
> output pushed into the database using REST too. It might be
> interesting to look at eliminating the XML parsing step and have
> phpDocumentor push the data directly using web services.
>
> All the best,
> Chris.
>
> On 26 February 2013 20:15, Herman Peeren <
herman...@gmail.com
> [5]>
> wrote:
>
>> Hi Mike,
>>
>> There is no timetable, no clear goal and no committed working group
>> (yet). Chris has done a lot to improve the wiki-documentation on
>>
docs.joomla.org [1] over the years. One of the often heared wishes
>> is to get better documentation, especially for the Platform /
>> Framework, as it is essential for the productivity of (new)
>> developers. Chris has now made some suggestions and some people have
>> shared their opinion about it. It is still in an exploratory phase:
>> looking what we have, what possibilities and needs are and choosing
>> goals and tools.
>>
>> I think, a next step should be TO SET SOME CLEAR GOALS THAT CAN BE
>> ACCOMPLISHED WITHIN AN OVERSEEABLE TIMEFRAME and GET SOME PEOPLE
>> TOGETHER who want (and are able) to commit to such goals.
>>
>> The Joomla project consists of several parts, like the Platform
>> (framework) and the CMS. We also have several channels of
>> communication, like fora (mainly for users / integrators), etc. On
>> Google Groups we have 3 main lists, which are mainly for developers:
>> this Platform list, a CMS list and a general list. At the moment
>> there are several discussions on the general list mentioning vision,
>> leadership, setting goals, roadmaps, working groups and
>> organisation. So questions about it are vivid, but there is no
>> consensus on all points. That is also one of the unique aspects of
>> the Joomla projects: it is more organic and less centrally directed
>> than many other open source projects. Sometimes it is tiring,
>> sometimes there is more debate than code and it always takes some
>> time. But this typical process is also what makes it so unique. Most
>> of the time things happen, because some people do it (because they
>> just need it) and then they present it to the community.
>>
>> I want to do some small tasks in this group and help getting it on
>> the rails, but as Ive set other goals for the near future allready
>> (besides work, which is mainly custom Joomla components, mainly: to
>> at last make Doctrine easily available in Joomla, refactor some
>> core classes with that and show the benefits of it for development),
>> I cannot commit to a big task here. There is however one thing Im
>> especially interested in: to use our current Joomla (Platform and
>> CMS) to develop some of the features we are talking about here. You
>> talk about Twig, but we have our own templating system and some
>> great frontend developers. Or should we integrate some Twig and what
>> you did with it into Joomla (some people have a Symfony-allergy
>> however ;-) ). Maybe we can even do something with Doctrine + Joomla
>> in this project; then Ill certainly participate more actively.
>>
>> What looks most promising to me at the moment are the points where
>> we can "embed" phpDocumentor in some Joomla-application (be it a
>> cms-component or platform-application) to add some extra features
>> like user comments to documentation that is generated via DocBlocks.
>> But that is just my idea, right now.
>>
>> - Herman
>>
>> On Tuesday, 26 February 2013 18:04:26 UTC+1, Mike van Riel wrote:
>>
>>> Allow me to elaborate a little on the current status of the
>>> project:
>>>
>>> phpDocumentor2 is a complete rebuild of phpDocumentor1 and as such
>>> has certain features the original had not and is missing some
>>> features that the original did have. This is the main reason it is
>>> still in an alpha state, the code is mature but so far we have
>>> reserved the right to make BC breaks (mainly within the code
>>> itself; the command line interface hasnt had a BC breaking change
>>> for many releases).
>>>
>>> At current I am in the middle of the last great push, which is a
>> [2].
>> [3].
>>
>>
>
> --
> Chris Davenport
> Joomla Production Leadership Team
>
> [6].
>
>
>
> Links:
> ------
> [1]
http://docs.joomla.org
> [2] mailto:
joomla-dev-platform%2Bunsu...@googlegroups.com
> [3]
https://groups.google.com/groups/opt_out
> [4]
http://api.joomla.org
> [5] mailto:
herman...@gmail.com
> [6]
https://groups.google.com/groups/opt_out