Posted by psynaptic on October 26, 2008 at 2:08pm
| Project: | Views |
| Version: | 6.x-2.x-dev |
| Component: | Documentation |
| Category: | feature request |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed (won't fix) |
Issue Summary
I'm the maintainer of http://api.freestylesystems.co.uk and have noticed a problem with the @mainpage tag used in Views 2.x. If you take a look at http://api.freestylesystems.co.uk/api/6 you will see that the Views 2 documentation has overridden the normal front page for the 6.x branch.
Comments
#1
I have deleted the views/docs folder now so those links in the original post are not showing the symptoms of this any longer. Please see attachment instead.
#2
Breaks contrib.api.rtk0.net as well, subscribing.
#3
Hmm, possible workaround: I added a command to touch my mainpage include file after every update, seemed to do the trick.
#4
Well, that's by design. API only supports one @mainpage per project. What were you expecting?
#5
That modules wouldn't be so rude as to include a @mainpage in their own code?
#6
The API module does not have a concept of what modules are. It should have that above branches so we can more-effectively documents contrib modules. When that is done, a @mainpage would be a good thing in a module.
#7
#218306: Allow multiple, partitioned paths to be indexed
#8
#9
See http://drupal.org/node/1354#contrib for why this needs to be changed.
#10
On the assumption that api.module was never intended to do both contrib and core simultaneously, this is not really a bug. Since I'm publishing documentation with doxygen for just Views, it needs a @mainpage.
I recommend you simply don't run Views documentation through api.module; it can't handle it, anyway, and this patch would break *my* published documentation.
#11
API module really needs to know what modules are: http://drupal.org/node/218306.
#12
I'm familiar with the Views API site, and it does not include the Drupal core API. I have also set up documentation sites for some of my contributed modules which do include the core API. See http://xmlsitemap.darren.oh.name/ for an example.
Contributed module documentation is more useful when it is integrated with the core API documentation. I agree that the current API module can't yet handle Views documentation, but does it break anything to use a group as the front page and leave Drupal's main page intact?
#13
Changing the title to better reflect what is being requested. If Merlin takes @mainpage out of his documentation, he'll need to get it from the Drupal docs. Then we can all be happy.
#14
...if I take @mainpage out, then my doxygen site won't have a frontpage. How is this acceptable?
#15
The Drupal docs will provide a @mainpage. It may also be possible to set another page as the front page.
#16
My doxygen site does not have the Drupal docs, therefore won't have a @mainpage.
I am not going to continue this discussion until it is made absolutely clear that I will NOT break the site that everybody uses for a site that a small handfull of people use. api.module can NOT handle classes, therefore does not do Views documentation properly. Supporting it at the expense of a site that *does* work is not good.
#17
I'm willing to go out on a limb and say that including the Drupal docs will not break your site. In fact, they would make your site more useful. However, it's up to you to change the status of this issue. I'll have to run a patched version of Views (and now Panels, too) until they can play nicely with the Drupal docs.