| Project: | API |
| Version: | 7.x-1.x-dev |
| Component: | Code |
| Category: | bug report |
| Priority: | major |
| Assigned: | Unassigned |
| Status: | active |
Issue Summary
Problem/Motivation
The API module allows you to have multiple Projects and Branches. However, links and searching are not working in sensible/useful ways across projects.
Scenario: You are setting up an API site for Drupal Core, Views, Panels, CCK, and FileField documentation. Each one is set up as its own Project, and within each Project, you have branches for 6.x/7.x (core), or 6.x-1.x, 6.x-2.x, 7.x-1.x, etc. (contrib).
Problem 1: Links are not made across projects. So if you're on a Drupal Core function page, you'll see all function calls there turned into links to other Drupal Core functions. But if you're in Views, you won't see links to the Drupal Core functions; FileField won't link to CCK functions, etc. Same for topics, files, etc.
Problem 2: The search blocks are currently set up to search across projects within a branch -- meaning that you can search "6.x", and any branch labeled as "6.x" in any project will be searched. And you can search "6.x-2.x", and any branch labeled as "6.x-2.x" in any project will be searched. However, this doesn't really make sense, because there is not really any correlation between CCK 6.x-2.x, FileField 6.x-2.x, and Views 6.x-2.x, for instance. This also is confusing, because all of the other API project navigation and breadcrumbs stay within a certain project and then within a certain branch.
Proposed resolution
PROPOSED RESOLUTION #1:
One possible resolution is what psynaptic does on drupalcode.org: put everything into one big project rather than having separate projects for Core and each Contrib module. The advantage is that neither of the two problems above applies. The disadvantage is that you have to pick one particular branch for each module (e.g., you can't have both 6.x-1.x and 6.x-2.x probably).
If we assume this is the best way to set up the module, then probably the search functionality should be changed so that you are only searching within a single project/branch, because we would be in a situation where different projects would be assumed to not be related at all (e.g., a site displaying docs for Drupal and WordPress).
PROPOSED RESOLUTION #2:
A second possible resolution is to allow the project/branch setup in the scenario above, but revise the way links and searching are done. Assuming we want to do this (note that Comment #12 below has some observations about the current set-up and terminology), here is a proposed resolution (from comment #13 below).
a) Assume that the Project associated with the default Branch is the default Project (note that we only have a concept of a default branch currently, not a default project). We're probably kind of doing that already, but not doing much (anything?) with the information. Also assume that the default project means "core" for purposes below.
b) Add additional fields to the Branch table and admin add/edit screen:
- Dependencies (branches): I think when we are entering branch information, we need a way to designate specifically which branches of which projects correspond to this branch. For instance, if I am entering information for Calendar 6.x-2.x, I might want to designate that the functions it calls come from Views 6.x-2.x, Date 6.x-2.x, and CCK 6.x-1.x (I made those up, but you get the idea). This would be optional.
- Core branch: We also need to choose which Core branch this corresponds to. It could be part of Dependencies, but I think it's a special case and should be separate.
- Most current: checkbox to indicate that within a particular Core Branch, this is the most current project branch. For instance we would say that Views 6.x-3.x is the current 6.x branch, not 6.x-2.x. But we'd also want to say 7.x-3.x is a "most current" branch (within core 7.x).
c) When we make function links, choose the first of these that is found:
1. PHP functions (the PHP branches).
2. The current branch within the current project.
3. The designated Core branch and the designated Dependency branches (if any).
4. Maybe don't check anything else? Or maybe check other branches marked "most current" within the same core branch, in case a dependency was missed?
This also needs to apply to the "functions that call this" and "functions that invoke this" sections/pages.
d) When we search... I can see the following being useful:
1. Search across a "core branch", looking for items in both Core and the "most current" branches of other projects that correspond to this core branch.
2. Search within one branch of one project.
Remaining tasks
PROPOSED RESOLUTION #1:
1. Make search just act within a single project.
2. Edit the documentation on http://drupal.org/node/425944 to explain the new behavior.
3. Use this scheme to build api.drupal.org (rather than having a separate Examples project for example).
PROPOSED RESOLUTION #2:
1. Implement the new scheme for linking and searching, as well as the new fields in Branch table/admin.
2. Create sample code and tests for the new code. Note that there is some sample code that could be added to the test samples attached to comment #5 here (but see comment #9 for a correction); this sample code may soon be committed as part of #544546: Hide listing links that would go to empty pages.
3. Edit the documentation on http://drupal.org/node/425944 to explain the new behavior.
User interface changes
To be determined.
API changes
To be determined.
Original report by rfay
In the top of ajax_example.module there is an @link:
* @link ajax AJAX Framework documentation @endlink and at theThis should point to the ajax group in ajax.inc:
/**
* @defgroup ajax AJAX framework
* @{But as you can see at http://api.drupal.org/api/examples/ajax_example--ajax_example.module/gro..., it doesn't turn into a link.
So unless I'm just missing something stupid, something is broken on group linking. Correct me if I've done something stupid.
Comments
#1
The problem is that you are trying to make a link from a page in one project to a group in another project. I don't think that works.
#2
drumm says this is a bug.
For instance, the Drupal Core functions in the Examples project source code are not turning into links. See url() call on http://api.drupal.org/api/examples/ajax_example--ajax_example_graceful_d... for one example.
#3
For unit tests, we want another "project" next to http://drupalcode.org/viewvc/drupal/contributions/modules/api/tests/sample/ and doc comments to demonstrate what should (and shouldn't) work. Ideally, I'd like some unit tests too.
#4
I think that #1007736: Automatically link filenames in documentation across projects? is a duplicate of this issue. It's talking about files rather than topics, but I'm pretty sure it's the same issue?
#5
Here is a zip file with a second sample project for testing this. I have verified that if I make an API site containing the existing tests/sample directory as one project, and this new sample2 directory as a second project, the links to not work as described in the sample2/sample2.php comments.
IMO, both in-code and in-comment links should work. But we may need to think about this a bit. I'm not sure what it should do if there are multiple instances of a particular function name. We can't really assume that branch names are the same across projects -- for instance, Drupal has 6.x and 7.x, while Views has 6.x-2.x, 6.x-3.x, and 7.x-3.x... So if you were in Views 6.x-2.x, would you be able to know that the Drupal core functions you want to link to are in Drupal 6.x and not Drupal 7.x?
Anyway... here's the test file...
#6
sub
#7
Sure would be nice to get this fixed. See #1289930-19: Give more detailed examples of hook_perm inside of page_example.module
#8
I'm trying to understand exactly what it is we want to happen, so I'm reading through related and duplicate issues. Here's a comment that drumm made with #1007736: Automatically link filenames in documentation across projects? that seems helpful in describing the goals:
Not sure if I can take this on, but I will try to help by clarifying what it is we want to do.
#9
@jhodgdon: in the sample2.php @file summary, it says "sample file to make as a new branch" but isn't the point of this to test a second *project*? So wouldn't it be better if the summary said "sample file to test a separate project" ?
Just trying to understand; may be I'm not getting it.
#10
Yes, that would be a better summary. Sorry for the confusion! :)
#11
Upping priority (marking "major" things that I'd like to see addressed sooner rather than later).
#12
I'm revisiting this. I think we need to have more information in the branch/project setup, to support a solution to this issue as well as
#770364: Searching within a branch across projects doesn't make sense
So here are some observations about the current setup. Currently, when you set up a Branch (I'm only worried about "files" branches here), you enter:
1. Project ID (db field: project). This is used for:
- A unique text ID for a project
- URL prefix for every page belonging to this project
- Two branches entered with the same project ID are considered to be part of the same project.
2. Project title (db field: project_title). This is used for:
- On an API object page (constant, class, etc. -- NOT functions though), when the other versions of the object are listed at the top, they are grouped by project, and the project is shown using this title. Function pages' version section is not grouped by project, and doesn't show the project name at all (would take up extra space).
- On listing pages and the default branch home page, there's a section at the bottom for Other Projects, and the link titles are the Project Title (presumably just choosing one of the entered project titles from one of the branches; they don't technically have to be the same, but that's probably OK).
3. Branch ID (db field: branch_name). This is used for:
- A unique text ID for a branch
- URL suffix for every page belonging to this branch
- Currently when you search, you are searching across all Projects, within branches with the same branch ID
- Used in constructing the title of the Search block (it says "Search branch_name").
- On an API object page (constant, class, etc., and including functions too), when the other versions of the object are listed at the top, the branch is indicated with the branch ID.
4. Branch title (db field: title). This is used for:
- The title of the first link in the branch navigation block (takes you to the branch home page)
- Used in breadcrumbs
- Used in the HTML HEAD page title
5. You can designate exactly one Branch as being the default branch, across the entire API site.
#13
In order to support #8 above (to resolve this issue), and also to resolve #770364: Searching within a branch across projects doesn't make sense, here's what I think we need to do:
a) Assume that the Project associated with the default Branch is the default Project. We're probably kind of doing that already, but not doing much (anything?) with the information. Also assume that the default project means "core" for purposes below.
b) Add additional fields to the Branch:
- Dependencies (branches): I think when we are entering branch information, we need a way to designate specifically which branches of which projects correspond to this branch. For instance, if I am entering information for Calendar 6.x-2.x, I might want to designate that the functions it calls come from Views 6.x-2.x, Date 6.x-2.x, and CCK 6.x-1.x (I made those up, but you get the idea). This would be optional.
- Core branch: We also need to choose which Core branch this corresponds to. It could be part of Dependencies, but I think it's a special case and should be separate.
- Most current: checkbox to indicate that within a particular Core Branch, this is the most current project branch. For instance we would say that Views 6.x-3.x is the current 6.x branch, not 6.x-2.x. But we'd also want to say 7.x-3.x is a "most current" branch (within core 7.x).
c) When we make function links (see comment #8 above -- this would be a slight variation):
- Check PHP functions (the PHP branches) first.
- Check the current branch next (i.e. linking within the current branch/project).
- Check the designated Core branch and the designated dependency branches (if any) next.
- Maybe don't check anything else? or maybe check other branches marked "most current" within the same core branch?
d) When we search... Not sure what to do about that... Maybe the search functionality is for a "core branch", and it searches across all branches marked "most current" in that core branch? Yes, I think that would make the most sense.
Does this make sense?
#14
Note to self: If we do something like this, we will need to edit http://drupal.org/node/425944 with the new instructions.
#15
psynaptic posted two comments on #770364: Searching within a branch across projects doesn't make sense relevant to this discussion; moving further discussion here. See comment #6 and the two following comments.
In response to #8 on the other issue... See my comments above on this issue #12/13...
The advantage I see to this proposed scheme [having each drupal.org project -- contrib module, theme, Drupal core, etc. -- in its own project] is that we could, for instance, have both Views 6.x-2.x and 6.x-3.x available, and then we can link other modules to which Views version they support. In principle anyway... And then when we're doing cross-project linking, we can link to the relevant project/branch.
api.drupal.org does not display code for minor versions of Drupal Core now (6.1, 6.2, 6.3, ...) -- it just does branches (6.x, 7.x). It seems to me that the site would be *huge* if we did minor versions, without much benefit to the viewer. I mean, if you really need to know what the code did in a past version, you can download it and look at the code. But for most purposes and most people, I don't think having each exact version displayed is relevant. The code doesn't tend to change much between releases, and hopefully the API doesn't (and if the documentation has changed, it's to fix a bug such as that the doc was inaccurate or incomplete, so the latest version would be what you want to see anyway).
Also consider that the list of "other versions" at the top of function pages would get pretty large if we had each minor version indexed... I mean, take this as an example:
http://api.drupal.org/api/drupal/includes--database.pgsql.inc/function/d...
We already have 5 versions listed with just major branches...
Anyway... I think there are benefits to separating each project out, if we can have a scheme like I outlined above to handle the linking and cross-project "search within branch" in an intelligent way. And I don't think it's too much to code -- it will require some refactoring and rewriting, but it should be worth it.
#16
I decided to close #770364: Searching within a branch across projects doesn't make sense as a duplicate of this issue. There is some good discussion and information there...
#17
I just wrote an issue summary for this issue, incorporating the duplicate issue.
#18
Note that the sample code from comments #5/9/10 above is probably going to be included in a patch for #544546: Hide listing links that would go to empty pages (the code can serve testing purposes for both modules).
#19
@psynaptic, @drumm, and anyone else interested...
Please review the current Issue Summary and offer thoughts on which of the two Proposed Resolutions I have listed there makes the most sense (or if there is a third option I haven't thought of, or if I've made some logic error in one of those two options). Thanks!
#20
#1 is not a good way to set up API module. Different projects should be treated as such, not crammed into one codebase.
#2 seems best, but I'd want to keep it simple for now.
- Having branches take priority, like core and php is good. I'd implement this as a priority setting for branches so we aren't hard-coding php and core being too special, and maybe it will be useful otherwise. It would be good to have this "priority" work with some of the existing weight, assuming that is not confusing.
- I'm not sure I like using dependencies. It might be okay if those are automatically gotten from the .info file or elsewhere. I want it to be easy to add more projects.
- I think for now, we should search and link aggressively, and handle problems as more projects are added. My goal is to parse all of contrib, but that won't happen quickly.
#21
I'm not sure what you mean by "search and link aggressively", especially in the case where we might have Views 6.x-2.x and 6.x-3.x both available. I'm also not sure how to make search/links work sensibly without having a concept of dependencies... yes of course, reading them from the .info file would be ideal, assuming the .info file specifies version compatibility too (for instance in Views dependencies, 6.x-2.x vs. 6.x-3.x, I think the version required is in some views.inc file and not in the module.info file, but maybe I'm wrong about that).
So maybe you can describe the simpler scheme you are thinking of? Because the concept #2 I outlined in the issue summary was about as simple as I conceive of making it, while still making it all sensible and workable, and avoiding all the problems described in the issue summary.
#22
Also as far as #1 not being sensible, it seems that many users of the API module do it that way, so it can't be totally crazy. :)
For instance, rfay mentioned in IRC today that Drupal Commerce's site does that, and psynaptic is doing that with all of contrib, right?
There are two reasons this *might* make sense: (a) the links work fine if everything is crammed together and (b) no need to enter information about each project into the API admin screens, which would be tedious for 2000+ modules.
#23
We still need to figure this out... Here is a new proposal.
a) I think we need to separate out several aspects of Branches and Projects, instead of trying to lump them all into the Branches table:
Project - Information about one particular project (in the drupal.org project sense):
- Project ID (numeric, auto-generated primary key - unless we just use the short name? Probably doesn't matter much either way).
- Short name (currently $branch->project) - URL-safe text, generally the project short name on drupal.org
- Title (currently $branch->project_title) - Human-readable text, generally the project's full name on drupal.org
- Core - If true, this is the "core" project, which has a special meaning for links. Only one project can be "core", so probably designate this using radio buttons like on the current API page.
Core branch - Information about a major Drupal version branch:
- Branch name (e.g. 6, 7, 8 -- or you could choose to use 6.x, 7.x, 8.x on your site I guess)
- Default - if true, this is the default branch (the one you get when you visit a page that doesn't have the branch defined). Only one core branch can be the default, so probably designate this using radio buttons like on the current API page.
File branch - Information about one particular branch (in the Git sense) of one particular project.
- Numeric branch ID (primary key, auto-generated, not visible to admin)
- Project (choose from the list of projects)
- Core branch (choose from the list of core branches)
- Branch name (such as 8.x, or 6.x-3.x, depending on the project) - corresponds to the Git branch - needs to be URL-safe
- Branch title (such as Views 6.x-3.x, or Drupal 6.x)
- Current (yes/no checkbox) - If true, indicates this is the latest development branch for this project/core branch. For instance, Views 6.x-3.x would have value yes, Views 6.x-2.x would have value no. [As a first pass, we could default this to always "yes", and add the ability to have multiple branches per core branch later on.]
- Dependencies - list of other branches (by numeric branch ID internally, choose from auto-complete list of branch titles in the UI) that this branch depends on (such as designating that Views 6.x-3.x depends on CTools 6.x-1.x). [As a first pass, we could leave this out, and add the ability to have dependencies for linking later on, see below.]
- Included/excluded directories
- I think we can get rid of the "status" db column (it is really only being used to distinguish between PHP and file branches).
PHP branch: Information about PHP functions such as php.net
- numeric branch ID (primary key, auto-generated, not visible to admin)
- Function list URL
- Function link URL
- I think we can get rid of the text branch identifier for these branches, and just use the numeric branch ID.
b) URLs
URLs for pages would remain the same as they are now:
items: api/[project]/[file]/[type]/[name]/[branch]
listings: api/[project]/[type]s/[branch]
files: api/[project]/[file]/[branch]
branch landing: api/[project]/[branch]
Where:
- [project] is Project -> Short name
- [branch] is File branch -> Branch name
- [file] is the file name with / replaced by !, starting from the common root directory
- [type] is function, class, constant, etc.
- [name] is the function name, constant name, etc.
c) Breadcrumbs and navigation - remain the same as they are now.
Breadcrumbs: Home | API reference | [branch title] | [file] | [class]
Where:
- [branch title] displays (File Branch -> Branch title), links to branch home page
- [file] displays the file name, links to file page
- [class] displays the class name (if applicable), links to class page
Navigation (links to other versions) on function pages: [branch] [file] [signature]
Where:
- [branch] displays File Branch -> Branch name
- [file] displays the file name
- [signature] displays the function signature with params
Navigation on non-function pages: other versions are links displaying File Branch -> Branch title
d) Links - When we make links in code and documentation, we would make a link with the first of these to yield a match:
1. PHP functions (the PHP branches)
2. Current file branch (i.e., linking within the current branch/project).
3. Designated Core project, in the designated Core branch (e.g., linking from Views 6.x-3.x to Drupal Core 6.x functions).
4. [if implemented] Dependency branches (e.g., linking from Views 6.x-3.x to Ctools 6.x-1.x).
5. Maybe also check other branches marked "most current" within the same Core Branch, but only if this branch is also marked "most current"?
e) Searching
We would have one search page for each defined "core branch", and it would search across all corresponding "most current" branches for all the projects.
It might also be useful to define a project/branch-specific search, for instance to limit the search to Views 6.x-3.x, although we do already have branch-specific Functions, Constants, etc. pages, so I'm not sure how useful that is?
#24
From my experience doxy-fying Examples, it seems that the group is the basic atom of documentation. There are two main use-cases: Someone who wants to know the profile of a function, and someone who wants to learn stuff in more general terms. The former are served well, and the latter are kinda screwed unless someone gives them a specific URL.
Groups allow a grouping of files and functions and concepts, and a.d.o could allow for browsing around these groups and drilling down and back up. Currently this can't be done. For instance, start here: http://api.drupal.org/api/examples/email_example%21email_example.module/... Note the handy @group explanation of what's going on here. Click on a function. Click on the module file. Where did the @group text go? It's been replaced with the @file text, with no indication to the user why this might be, and no way to navigate back to the instructive text.
So: You'd want a clear URL scheme that includes groups and projects as the namespace. Like for instance:
api/[project]/[group]/
...would show you a list of versions for that group the default version's documentation, functions in the group, and a list of files that belong to the group. So linking to:
api/examples/node_example/
would show you the documentation inside @group node_example, regardless of which file(s) it came from, with links out to the functions and files. Currently you need:
http://api.drupal.org/api/examples/node_example%21node_example.module/gr...
..to get to the same thing, which requires knowing which path and file defines the group. Even /api/group/node_example/7 fails, and it shouldn't.
Then on a file or function page, you'd need to always link back to the group for that function.
Then the onus is on the doxy author to put everything in the proper group, which is good anyway.
I'd be happy to help make this work.
#25
#24 is not related to this issue. This issue is about links between the different projects (e.g., Examples and Drupal and Views), not links within one project. So please do not continue this discussion here.
(But as a note, you are just clicking on the wrong link. If you want to get back to the group/topic page, you click on the Topic link, not the File link. It is shown on the function page under the heading "Related topics" -- in the user interface of the API module, they are called "topics" not "groups".) (And again, further discussion on a separate issue please, or ping someone for help in IRC.)
#26
#25 @jhodgdon "This issue is about links between the different projects (e.g., Examples and Drupal and Views), not links within one project."
Right. We have projects, and those projects are organized into groups in the doxygen doc blocks. Drupal should have a @defgroup drupal. Examples has a @defgroup examples. Thus: groups are the atomic unit of the doxy-based API pages. Therefore linking between groups solves the problem of linking between projects.
"(And again, further discussion on a separate issue please, or ping someone for help in IRC.)"
I don't need help. I am offering help.
#27