Public API: Volunteer to Help Define It

[Nick Savov]

Hi all,

Is there anyone that would be willing to help define a public API? This would be a big help for stabilizing CMS updates and for focusing new unit tests around that API until it's fully covered.

A working group can be formed and then the work can be presented to the community for feedback/revision. Once it's relatively finalized, it can be sent to the Production Leadership Team for feedback/revision, and then eventually a vote for it.

So who's interested? :)

Kind regards,

Nick

[Bakual]

I was going to do a similar post but you beat me :)

[Michael Babker]

So a little background (from my individual perspective and something I also addressed to the rest of the PLT):

3.2 included a refactoring of com_config which included moving some files around.  A bug report came in about this moving around (http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEdit&tracker_item_id=32478) since another developer was including one of the classes that was moved, and since component classes aren't autoloaded (aside from some cases in the refactored com_config), this broke their code.  Until this point, I had never thought twice about a component being considered part of the API, but this presents an interesting use case.

So, from my perspective, part of this discussion would help to define how much of the core distro we truly consider part of the API and what parts of the core distro that developers should be highly encouraged to not extend since those aren't actually in the API and breaking changes will happen there without notice (such as this case which started the discussion for me).

--
You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cm...@googlegroups.com.
To post to this group, send an email to joomla-...@googlegroups.com.
Visit this group at http://groups.google.com/group/joomla-dev-cms.
For more options, visit https://groups.google.com/groups/opt_out.

[Bakual]

Similar thing to discuss: When we are making changes to the generated output (in a view or in a layout), we potentially break templates. Do we consider this part of our backward compatibility promise (or API) or not? If yes, only the part which the view does or also what the layout does?

As an example: For 3.2.0 we changed the way how leading and intro articles and links are preprocessed for the blog layout. The processing is done in the view itself, not in the layout and the layout for protostar and beez were changed accordingly to reflect that change. So core works fine but each template which made an override for the blog layout is broken now. Is this a B/C break or not?

[brian teeman]

When it comes to templates where do you stop. In the use case you give I would perhaps agree its a B/C break BUT what about the TFA additions as that wont work either if a template is overriding mod_login. Are we forever held back because someone overrides a core feature even if that is only a view. 

[Bakual]

That's why I think we might have to define here as well where we stop. We have an API directed at the 3rd party extensions and also kind of an API directed at the templates.

Personally I think we should not change existing output of the view, but we should be allowed to add stuff (like TFA) to it as this usually doesn't break anything. And we should be allowed to make changes in the layouts, even if this may break templates which rely on the markup of the core (not using overrides).

But that for sure needs to be discussed and defined first.

[Amy Stephen]

Really happy to see this.

On Saturday, November 16, 2013 2:30:04 PM UTC-6, brian teeman wrote:

When it comes to templates where do you stop. In the use case you give I would perhaps agree its a B/C break BUT what about the TFA additions as that wont work either if a template is overriding mod_login. Are we forever held back because someone overrides a core feature even if that is only a view. 

Remember, a UI is not part of the API.

If developers want to protect against changes to the rendered output, they already have the tools to do that by using template overrides.

Defining and testing the extension API and continuing to educate site builders on these practices should provide excellent protection from unanticipated change. 

[Andrew Eddie]

On Sunday, 17 November 2013 04:05:53 UTC+10, Nick Savov wrote:

Hi all,

Is there anyone that would be willing to help define a public API? This would be a big help for stabilizing CMS updates and for focusing new unit tests around that API until it's fully covered.

I'm a bit confused by what you mean from a developers point of view. The API is defined by the nature of the visibility you assign a class property or method (the use of `public`, '`protected` and `private` keywords). When you say "public" what do you mean? Public as in a document that everyone can see, or public as in the visibility of PHP language constructs?

Secondly, why aren't DocBlocks considered the definition of the public (still unsure of what you mean there) API? That's the whole point of actually including them.

Finally, are we talking about just PHP or does this include JavaScript as well (CSS and HTML aren't an API in my book, they are "standards", so I'm assuming you are excluding them)?

Thanks in advance for the clarification.

Regards,

Andrew Eddie

[Michael Babker]

This goes beyond what is in the libraries folder, doc blocks, or visibility keywords.  As in my example above, part of this would be to define what classes outside the libraries which are commonly considered to be the base API would actually be part of that.  So basically, one of the questions to answer is are components part of the API that developers should consider available for use and follow the same rules as far as deprecations and renaming goes or are they "use at your own risk" type deals.

--

[Andrew Eddie]

My take is whatever is distributed follows Semver. I was assuming that
we were talking about all the code in the CMS, not just the libraries
(and I'd make the same rules apply to any code we officially
distribute).

So, if the exercise is "what is the public API?", then I would say all
of the executable PHP or JavaScript code.

If the exercise is what falls under Semver, then I would say the PHP
and Javascript and CSS. I'd have to think about how HTML layouts would
be classified because I'm not sure what backward incompatible markup
would look like or how much change would trigger a minor or major
update under Semver (as Thomas has already brought this up).

Now, things get even more interesting (in a good way) if you consider
breaking each extension into a package and allowing that package to
follow it's own release strategy.

But before I go down the track of "distributions are part of the
answer", I just want to have a clear idea of the problem we are
actually trying to solve.

Regards,
Andrew Eddie

> You received this message because you are subscribed to a topic in the

> Google Groups "Joomla! CMS Development" group.

> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/joomla-dev-cms/YhPvWTJS4go/unsubscribe.
> To unsubscribe from this group and all of its topics, send an email to

[Amy Stephen]

Andrew -

For purposes of this discussion, let's define "Extension Developer API" as those classes and methods which are intended for use by developers to create extensions.

Towards that end:

• ContentViewArticles would be excluded from the list (It's not a class for developers to use to create extensions)
• But the class it extends, JViewLegacy would be included. (It is a class intended for use by developers to create components.)
  
• Even though JViewLegacy extends JObject (and it has public methods) JObject would likely not be included in this list as it is not a class for creating extensions.

Sorting out the "Extension Developer API" would be useful to the distributions project in that it would provide clarity as to what shouldn't change. With that, one could put into place a services layer to provide access to the v 3.5 API and the v 4 API.  The concerns about change could be put to rest if the CMS had unit testing on the "Extension Developer API." Provided tests continue to pass, who cares what happens under the hood?

An API definition that broadly states "all executable code" limits what can be done with code that shouldn't really be used directly by extension developers anyway. Not as useful.

A "Framework Developers API" would be a different set of classes and methods.

Symfony uses an @api docblock key to help clarify their "Framework Developers API" since visibility really isn't enough. Joomla might need a @extension_api and @framework_api indicator to add to the docblocks. 

This problem isn't unique to Joomla. Lots of projects have a great deal of code and are under pressure to stabilize and manage changes for third party developers. Sorting out the distinction of what they should or should not be using goes a long ways to empowering those working on architectural improvements internally.

[Fedir]

I always thought like next:

if system have a documentation for "this" then it "public API",

otherwise it not a public :)

Неділя, 17 листопада 2013 р. 12:08:28 UTC+2 користувач Amy Stephen написав:

[Michael Babker]

That's a good way of looking at it.  Until that tracker item I linked before, I personally considered our "Extension Developers API" to be just the libraries and considered components downstream consumers of that API but not a resource developers would use.  Obviously, that isn't totally the case.

Ensuring all code follows SemVer is a good step, but by that rule, the front end config stuff and Template Manager would've forced us into a 4.0 as there were a lot of changes in those components for these enhancements, including the B/C break of shifting non-autoloaded files around.

--

[Andrew Eddie]

My take on distributed code is fairly puritan. If you distribute it,
it can be used an Semver applies to every line. That probably explains
why the problem is foreign to me. I have a few problems with it:

1. Is an administrative overhead that we don't have the resources to maintain.
2. The people the concept is trying to help don't appear to be driving
the conversation, ergo, it will probably be a lot of effort wasted.
3. It will create unnecessary arguments about each and every line of
code as to whether extension developers should use it or not.

Regards,
Andrew Eddie

> --
> You received this message because you are subscribed to a topic in the

> Google Groups "Joomla! CMS Development" group.

> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/joomla-dev-cms/YhPvWTJS4go/unsubscribe.
> To unsubscribe from this group and all of its topics, send an email to

[Andrew Eddie]

Ok, so I understand part of the problem now.

Take JTable. The developer of com_foo extends it and adds a
`getFoobar` method. At some point in the future, the CMS also adds a
`getFoobar` method but with a different method signature to com_foo.
Sites using com_foo suddenly break when they upgrade the CMS.

This is an unfortunate situation but it's not a break in backward
compatibility on our part. It's an unfortunate collision which is
bound to happen from time to time. The reality is though no amount of
documentation is going to prevent it because it could happen with any
distributed class. It's the reason we remind developers constantly to
test their extensions during the beta phase.

The other way I look at this issue is that you effectively want to
write in exemptions to Semver (via some tag presumably) for part of
the API. I don't think that's a good idea because it won't help the
developers that know what they are doing, and the developers that
don't know what they are doing are still going to blame us for
problems of their own making anyway (and those developers aren't
driving this conversation anyway). Ergo, negative nett benefit because
we've wasted a lot of time for nothing.

_shrug_

Regards,
Andrew Eddie

[Amy Stephen]

On Sunday, November 17, 2013 3:03:15 PM UTC-6, Andrew Eddie wrote:

The other way I look at this issue is that you effectively want to
write in exemptions to Semver (via some tag presumably) for part of
the API. I don't think that's a good idea because it won't help the
developers that know what they are doing, and the developers that
don't know what they are doing are still going to blame us for
problems of their own making anyway (and those developers aren't
driving this conversation anyway). Ergo, negative nett benefit because
we've wasted a lot of time for nothing.

If the motivation behind this is escaping blame from developers who are not fully participating in testing, then, yea, it's really a waste of time. But, if it's a way to sort out what is the CMS? what is the API for CMS developers? What belongs to the underlying framework? And can change within each of those layers be better managed, then, the information has a lot of potential.

In terms of semver, this uncoupling is critical. Let's take the Filesystem package, as an example. If the method signature changes on the getFile method, that represents an API change and, as such, should trigger a full version number.

If the Filesystem continues to be closely coupled to the CMS API, then, the CMS version would also have to increase a full version. There are no exemptions to change. If the API changes, then the version is bumped up a full count.

If a facade layer is added and a configuration setting so that either (or both) Fileystem versions could be included, then the Filesystem version number changes are no longer tightly coupled to the CMS API, the facade separates the two. With that in place, the CMS API is the Facade, not the Filesystem classes itself, so changes to the Filesystem would not trigger a point release in the CMS.

Naturally, that gives a lot more room to operate to those working in the framework. Provided the CMS API is separate and distinct and there is a way to ease in those framework changes without impacting the CMS API, there is more of a clear path forward for innovation.

[Andrew Eddie]

On 18 November 2013 13:29, Amy Stephen <amyst...@gmail.com> wrote:
> If the motivation behind this is escaping blame from developers who are not
> fully participating in testing, then, yea, it's really a waste of time.

Blame isn't an issue here, at least not for me. I'm just trying to
define the actual problem we are trying to solve and what or who is
the driving force.

> But,
> if it's a way to sort out what is the CMS? what is the API for CMS
> developers? What belongs to the underlying framework? And can change within
> each of those layers be better managed, then, the information has a lot of
> potential.

It's all API to me. I don't see the problem.

> In terms of semver, this uncoupling is critical. Let's take the Filesystem
> package, as an example. If the method signature changes on the getFile
> method, that represents an API change and, as such, should trigger a full
> version number.

Correct.

> If the Filesystem continues to be closely coupled to the CMS API, then, the
> CMS version would also have to increase a full version. There are no
> exemptions to change. If the API changes, then the version is bumped up a
> full count.

In isolation, correct. In reality it's not a good idea to mess with
method signatures. You'd be better to invent a new package to work
off, or you create proxy methods. There are lots of ways to solve this
kind of issue.

> If a facade layer is added and a configuration setting so that either (or
> both) Fileystem versions could be included, then the Filesystem version
> number changes are no longer tightly coupled to the CMS API, the facade
> separates the two. With that in place, the CMS API is the Facade, not the
> Filesystem classes itself, so changes to the Filesystem would not trigger a
> point release in the CMS.

Yeah but at some point you've got to stop the recursive abstraction.
What does get interesting is how dependency management is affected
within a Composer paradigm.

> Naturally, that gives a lot more room to operate to those working in the
> framework. Provided the CMS API is separate and distinct and there is a way
> to ease in those framework changes without impacting the CMS API, there is
> more of a clear path forward for innovation.

I'm still struggling to understand the overwhelming motivation for
this. Adding layers of abstraction is one thing but telling developers
"here use this" but elsewhere "um, don't use this" just sounds really
confusing and an administrative nightmare. You'd be better off
declaring classes as `final` if you wanted to go down that route. I
see more value in bolstering our internal training material for
developers first to teach the teachable the right way to do things.

Maybe it would be better to list all the recent incidents that this
proposal is supposed to fix (and how "fix" is actually defined). Like,
I get we've got some funkiness happening with code-style and private
vars but is there more too it than that?

Regards,
Andrew Eddie

[Al Warren]

Pardon me for butting in. Regards an "API", what's more important to me than the API itself is the documentation. In the past, that's pretty much just a doc block tree on a web site. There's nothing that irritates me more. I can browse classes and doc blocks in my IDE.

Today I spent three hours trying to figure out how to put form data on separate tabs.It should not have taken that long. I use a couple of other frameworks and their documentation is fantastic, It's well organised and there are examples for almost everything. I can normally do something I've never done before using those frameworks in a matter of minutes because the docs are so well organized and presented.

The conversation here may have shifted to what to "call" an API. But, frankly, How the developers "see" the API is more important than what you call it.

[Andrew Eddie]

On 18 November 2013 16:26, Al Warren <wr5...@gmail.com> wrote:
> The conversation here may have shifted to what to "call" an API. But,
> frankly, How the developers "see" the API is more important than what you
> call it.

This is the conversation, and a very frank one, I really want to have.
How can we start it and who's willing to get serious about it? I'm in,
just tell me where to bring the pizza!

Regards,
Andrew Eddie

[Amy Stephen]

On Sunday, November 17, 2013 9:52:57 PM UTC-6, Andrew Eddie wrote:

On 18 November 2013 13:29, Amy Stephen <amyst...@gmail.com> wrote:

> If the Filesystem continues to be closely coupled to the CMS API, then, the
> CMS version would also have to increase a full version. There are no
> exemptions to change. If the API changes, then the version is bumped up a
> full count.

In isolation, correct. In reality it's not a good idea to mess with
method signatures. You'd be better to invent a new package to work
off, or you create proxy methods. There are lots of ways to solve this
kind of issue.

On that note, going to exit, stage right. Pretty clear continuing would be a waste of time. Either you are intentionally being difficult or we are simply not able to get on the same wavelength here.

[Adam Rifat]

+1 to what Al said...

[Andrew Eddie]

On 18 November 2013 21:25, Amy Stephen <amyst...@gmail.com> wrote:
>> In isolation, correct. In reality it's not a good idea to mess with
>> method signatures. You'd be better to invent a new package to work
>> off, or you create proxy methods. There are lots of ways to solve this
>> kind of issue.
>
> On that note, going to exit, stage right. Pretty clear continuing would be a
> waste of time. Either you are intentionally being difficult or we are simply
> not able to get on the same wavelength here.

Chill Amy :) Picture me saying that rubbing my fingers over 2-day old
stubble with a quizzical look on my face (we need better emoticons I
say!). I've said repeatedly I'm not getting the heart of the problem.
I have not said that you are imagining it, though. That said, the
comment above is still true - it's dangerous to mess with method
signatures (that is in fact why we go to a lot of trouble to define
Interfaces). If you find that you've stuffed up a method, it's better
to invent a new one and then just deprecate the old one. That's
certainly what we've done in the past, although some did apparently
not perceive the virtue of upholding the Queen's English iirc
correctly (not mentioning any names).

But to put it your way, yes, I'm not resonating with your wavelength
... yet. Please help me launch the penny in the air.

Thanks in advance.

Regards,
Andrew Eddie

[Andrew Eddie]

On 18 November 2013 21:31, Adam Rifat <ad...@littledonkey.net> wrote:
> +1 to what Al said...

@Adam and @Al - so I can ping you about volunteering to help with a
solution then?

Regards,
Andrew Eddie

[Adam Rifat]

Yes sure thing. Happy to do what I can.

[Al Warren]

I've pinged you  via twitter. I have some ideas.

[Al Warren]

Let me just throw something out there from Tom's semver page, "Managing software complexity is a hugely important part of keeping a project efficient, and that's hard to do if nobody knows how to use your software, or what methods are safe to call."

That's the one thing that has always really irritated me. Writing J software, at least for me, is highly inefficient because of the public API, developer docs, or whatever we choose to call it. I'm one of those who depend on documentation. At this age, I can't possibly remember everything. But I AM good at looking stuff up. If there's a resource available.

Which brings me to this point. And, I apologize in advance for stepping on toes. Call me a cynic or whatever. But I've at times wondered why there aren't any good consistent developer docs. The only plausible explanation I can come up with is it could be intentional. I've been in the background pre-fork and remember well some of the conversations around the support model some were staking their careers on. Good developer docs might be seen by some as a threat to that support model. I would hope that is not the case. I'm sure it's just a bandwidth issue. But the cynic in me has to wonder sometimes. That and I'm just getting old and cranky.

[Bakual]

Which brings me to this point. And, I apologize in advance for stepping on toes. Call me a cynic or whatever. But I've at times wondered why there aren't any good consistent developer docs. The only plausible explanation I can come up with is it could be intentional. I've been in the background pre-fork and remember well some of the conversations around the support model some were staking their careers on. Good developer docs might be seen by some as a threat to that support model. I would hope that is not the case. I'm sure it's just a bandwidth issue. But the cynic in me has to wonder sometimes. That and I'm just getting old and cranky.

Actually the answer to this is easy: Apparently nobody bothered to write the doc and keep it current. There are some good docs out there on docs.joomla.org, unfortunately they are often outdated.
So if you want good documentation with examples and anything, feel free to start writing them in the wiki. Anyone can contribute and every bit helps.

[Al Warren]

That would be a valid suggestion IF I wrote the software. The only way for me to document something I didn't write is to painfully slog through code until I understand what's going on. Doc blocks are only useful to a point. It's one thing to write up a proper doc block. It's quite another to document how, when, and where something might be used.

docs.joomla.org is mostly crowd-sourced by users. It should not be up to the users to document what a programmer had in mind when he/she created something.

[Bakual]

You might be interested in this discussion then: https://groups.google.com/forum/#!topic/joomla-dev-cms/llT8RQgRzeA ;-)

[Andrew Eddie]

On 19 November 2013 03:58, Al Warren <wr5...@gmail.com> wrote:
> Which brings me to this point. And, I apologize in advance for stepping on
> toes. Call me a cynic or whatever. But I've at times wondered why there
> aren't any good consistent developer docs. The only plausible explanation I
> can come up with is it could be intentional.

My personal belief is it's cultural and that is that the "core"
product falls second in line to 3rd-party extensions, books and
personal or company sites that are competing for traffic (in other
words, what *I* can get out of Joomla comes before what *I* can give
to it). I was very much convicted by Matt Mullenweg's talk at JWC. I
really think we need to be lifting the bar in terms of documentation
and I'm at the point where I'm prepared to be extremely snobby about
it - if you aren't prepared to make even a small effort with regard to
documentation, then you aren't a good fit for Open Source in general,
let alone this project and I don't care how whiz-bang the feature is.

I'm certainly prepared to JDL anything I've ever written provided we
have a good plan.

Regards,
Andrew Eddie

[Al Warren]

There are some good posts there (https://groups.google.com/forum/#!topic/joomla-dev-cms/llT8RQgRzeA). However, there is a big need for API documentation versus end-user documentation. It's one thing to document how to use a "feature". It's quite another to document how to use the API.

We need to go beyond relying on doc blocks in API documentation. We need something that is well organized and meaningful. I've resisted links to other frameworks, but here's an example of docs I use frequently - http://fuelphp.com/docs/. Forget it's someone else's project. It's a good example of how to publicly document code. Easy to navigate, concise, and with meaningful content.

Amy's right though. Someone needs to define what the API is from a code perspective. I'm more interested in how well it's documented from a developer's perspective.

[Andrew Eddie]

On 19 November 2013 06:55, Al Warren <wr5...@gmail.com> wrote:
> We need to go beyond relying on doc blocks in API documentation. We need
> something that is well organized and meaningful.

This is what we are doing with the Framework:

https://github.com/joomla/joomla-framework/tree/staging/src/Joomla/DI

It's mandatory to include the "how to" guide as well as good, complete
DocBlocks. I think we can go one more step and organise it better -
I'm working on an idea for that.

Regards,
Andrew Eddie

[Vic Drover]

Did you watch Den Nicholson's keynote? She had some good comments on documentation also.

Cheers,

Victor Drover
Founder and CEO, Anything Digital LLC (BBB Accredited)
Co-founder, Watchful.li
262-309-4140
 @AnythingDig | @watchfulli

--

You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.

To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-cm...@googlegroups.com.

[Andrew Eddie]

On 19 November 2013 07:20, Vic Drover <ad...@anything-digital.com> wrote:

Did you watch Den Nicholson's keynote? She had some good comments on documentation also.

Yes. For those that didn't, and correct me if I get her message wrong, documentation is best addressed at the beginning of the contribution process (aka, with the pull request in our case). I you tack it on to the end, the momentum from the initial excitement is waning, particularly if the review process has been long and arduous and you are less likely to get anything let alone anything of reasonable quality.

Regards,

Andrew Eddie 

[George Wilson]

Can I just add this - for all the talk about documentation is doing (the other long google group post and partially in this one). It doesn't really matter what people write on PR's for now unless the backlog is bought back under control. And it's still pretty much just me, Tom and Mark working on docs still and even I'm dropping right back at the moment cause of uni commitments.

Sure the docs are a mess - but if everyone's just going to talk and not actually do you may as well not bother. Also just because you didn't write the code doesn't mean you can't write docs ;)

Kind Regards,

George

[Andrew Eddie]

On 19 November 2013 11:10, George Wilson

<georgeja...@googlemail.com> wrote:
> Sure the docs are a mess - but if everyone's just going to talk and not
> actually do you may as well not bother. Also just because you didn't write
> the code doesn't mean you can't write docs ;)

Here's my personal situation.

I don't like the Mediawiki for developer docs (end-user UI is fine) so
I don't contribute to it and have used my own resources because of it.

I do like Github and Markdown.

I think publishing books through the normal channels is a waste of
time and can't cope with change.

I'd much rather do community documentation than stuff on my own sites
- the community is more important to me than my site traffic.

I've started this: https://github.com/eddieajau/joomla-developer-docs
- this is for "explain how to use the API" stuff that Al is talking
about.

If anyone wants to help my one-man black-op working group, great (just
raise an issue to ask questions). If the project wants to take it
over, more than happy. The issue tracker can be used to compile a
backlog. But I'm not using Mediawiki.

I too am sick of this conversation ending with nothing happening.

Regards,
Andrew Eddie

[Al Warren]

On Monday, November 18, 2013 7:10:05 PM UTC-6, George Wilson wrote:

Sure the docs are a mess - but if everyone's just going to talk and not actually do you may as well not bother.

What makes you think some of us aren't willing to "do"?

 

Also just because you didn't write the code doesn't mean you can't write docs ;)

Sure, I can pull up a class and understand most of what it does. But documentation is more than documenting some chunk of code. What's more important is documenting the application of that code. How it's used, why it's used, when it's used, etc. It's kind of difficult to do that without being able to read the original developer's mind.

[Al Warren]

On Monday, November 18, 2013 7:37:38 PM UTC-6, Andrew Eddie wrote:

Here's my personal situation.

I don't like the Mediawiki for developer docs (end-user UI is fine) so
I don't contribute to it and have used my own resources because of it.

I do like Github and Markdown.

I think publishing books through the normal channels is a waste of
time and can't cope with change.

I'd much rather do community documentation than stuff on my own sites
- the community is more important to me than my site traffic.

I've started this: https://github.com/eddieajau/joomla-developer-docs
- this is for "explain how to use the API" stuff that Al is talking
about.

If anyone wants to help my one-man black-op working group, great (just
raise an issue to ask questions). If the project wants to take it
over, more than happy. The issue tracker can be used to compile a
backlog. But I'm not using Mediawiki.

I too am sick of this conversation ending with nothing happening.

Regards,
Andrew Eddie

That's a perfect example of what developers really need.

I do have some ideas though. I gave an example in an earlier post. I believe those docs were generated using Spinx - http://sphinx-doc.org/intro.html. It takes a source repository and generates the html all at once. It uses reStructuredText instead of markdown but there are converters that can convert from markdown. What I like about it is you can manage it on git as a repository. Just an idea.

[Andrew Eddie]

On 19 November 2013 13:56, Al Warren <wr5...@gmail.com> wrote:
> I do have some ideas though. I gave an example in an earlier post. I believe
> those docs were generated using Spinx - http://sphinx-doc.org/intro.html. It
> takes a source repository and generates the html all at once. It uses
> reStructuredText instead of markdown but there are converters that can
> convert from markdown. What I like about it is you can manage it on git as a
> repository. Just an idea.

Yeah I had a hunt around last night. Symfony uses rst's as well. I
found 37signal's docs and sort of liked the simple approach they had
to it (see http://37signals.com/svn/posts/3181-our-api-docs-are-now-hosted-on-github)
and I sort of modelled the repo on that. I'm sort of in a "let's try
anything and refactor later" mood. I'll post topics for discussion on
https://github.com/eddieajau/joomla-developer-docs/issues so as not to
clutter this list.

Regards,
Andrew Eddie