Organize Examples in a way that the whole project can be understood

Since we're now including the examples module in the api.drupal.org docs, we desperately need a Table of Contents or something to make it easy to navigate all of the examples in this project.

Then the docs at contributions/docs/developer can point to the index page included with this project.

Here's a patch that moves the links from developer/index.php into an examples.index.php.

Once this is in, we can modify the developer/index.php to just use this syntax to link to this module's examples.index.php file.

@link examples.index.php Example modules @endlink

a base module is a good idea which provides a main landing page (text and list of enabled example modules) and maybe some base functionalities for the example modules, such as a main menu entry and main permission.

patch is an example for a base module.

We can probably scan module files and their .info properties for example modules instead of relying on a new hook, which might confuse people using these examples as base code.

Where is "contributions/docs/developer" located?

I tried "http://drupal.org/contributions/docs/developer" and got "Page not found".

@rfay, Thanks.

Looks like the paths have been changed a bit, but this pointed me in the right direction.

cvs.drupal.org/cvs/contributions/docs/developer
was redirected to
http://drupalcode.org/cvs/contributions/docs/developer (404 error)

I tried
http://drupalcode.org/
and was redirected to
http://drupalcode.org/viewvc/drupal/

The contributions folder is listed there.

ya, to keep the base module more simple and examples without the special hook is better. we can add a separate custom hook example later.

examples getting more and more with the time, maybe it's good the if the base module provides a separate examples menu block like the devel module.

just as a reminder: I'm starting to have the feeling the we should sepparate in some way core/api examples than other 'features' examples like token, or any of the features awaiting in the issue queue..

what if these non-core examples go to a documentation page in the corresponding project documentation page (so it must exists)? cck, ctools, there are a few in the issue queue as features to be included into examples.

That is a good idea, +1!.

On the other hand, about organizing this project:

Examples integration in api.drupal.org for D6 and D7 are different:
- D6 shows a list of links, each link pointing to an example module
- D7 shows a single link to an additional page.

Just testing, I've found extremelly dificult to reach the "examples" project navigating the documentation section of d.o. I had to click several links until I finally found the api.drupal.org link.

I agree with rfay at #1 that we may introduce a documentation page describing what each example module does, and link that page at: http://drupal.org/developing/modules . Other possible place where a link to that documentation page makes sense is here: http://drupal.org/node/326 (Working with the Drupal API)

You know, my english is not the best, I'm spanish, so.. anybody wants to review/rewrite it if I do write that documentation page?

I give you: http://api.drupal.org/api/examples/6

http://api.drupal.org/api/drupal doesn't have a direct link to examples. Also, I think it would be better for the main API page to simply link to the top Examples group as one item, rather than try to link to all the individual modules. Given the evolving nature of these docs, it's less work at that level.

The real problem is that Drupal doxygen brings all the groups up to the front page, ignoring the heirarchy. So if the canonical link is /api/examples, it gives you the main examples group and all the subgroups in a big long list. Confusing. But it gives links so you can browse the files and functions and constants, which is probably valuable.

I don't mind bombing through a bunch of this doxygen commenting task, but I want to be going in the right direction. Anyone see any other problems with the way the D6 examples API page is going?

Hah. Meant to post the comment on this thread: #767204: API.drupal.org: Rework Doxygen comments so people can navigate the comments

But I guess it still works here.

I made an .info and .module file for D7, and removed the .index.php file. Eventually we patch against core for a link from api.drupal.org, for the examples group.

This can be a basic template for how sub-modules can document themselves.

I think that for a beginner to Drupal (as I am) it is a bit difficult to find the way around the examples. It is not so clear which example to study first and which later. After looking at some of them, it became clear to me that there are some prerequisites (dependencies), although each of the examples is supposed to be stand-alone. For example menus are used in almost all examples, so it could be better if menu_example is studied first.

There may be other dependencies like this as well. It might be a good idea if these dependencies are somehow documented. Or it may be even better if there is a suggested order of studying the examples.

I'm calling this closed. Most of the ideas raised here have been implemented for 7.x and moving forward to 8.x.

We currently have #2209627: [meta] Module Checklist for Examples for contributors, and #1007276: [policy, no patch] Comaintainer practices and procedures for co-maintainers.