On #2106873-6: [meta][policy, no patch] Make Drupal 8 developer docs more discoverable we came up with a plan to make a better landing page for D8 documentation on api.drupal.org, with links to high-level overview topics.

So, for this issue: Make a first pass at that landing page, and put it into the Core repository (file core/modules/system/core.api.php), with stubs for the high-level topics (in same file). [Done! Patch committed was on comment #12]

Follow-ups: Improve the outline, write the topics. See child issues -- we'll leave this issue open until all the child issues are resolved.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon’s picture

Assigned: Unassigned » jhodgdon

It's time to do this... I will take it on.

jhodgdon’s picture

Status: Active » Needs review
FileSize
9.49 KB

Here's a first pass. Besides a review here, this needs to be parsed by the API module, and I'm working on that but unfortunately my API site is out of date for some reason so it wants to parse a whole lot of files besides this one and it will be a little while before I can verify the patch works as expected.

When we get around to committing this (or a similar) patch, we'll also want to remove the @mainpage that is currently in the Documentation git repository 8.x branch so that we use this one in Core instead.

I've filed a few follow-up issues to flesh out the defgroups here but more will need to be filed.

jhodgdon’s picture

FileSize
9.47 KB
1008 bytes

I remembered my laptop had a more updated API site, so I tested it out there and found a couple of problems.

This new patch has been tested in the API module. It successfully makes an API landing page and I verified that all of the links work as they should. Of course, the documentation in the new @defgroups is lame but that is kind of the point of this first patch anyway... Thoughts?

jhodgdon’s picture

FileSize
40.93 KB

Here's a screenshot of the top of the landing page on my API test site. It will look very similar on api.d.o when deployed, but there's a different theme and different tabs etc.
screen shot of top of new API landing page

jhodgdon’s picture

Assigned: jhodgdon » webchick

Assigning to webchick to review/commit as I better not do my own patch. :)

I did check the links and formatting after parsing with API module...

The last submitted patch, 2: 2148255-firstpass.patch, failed testing.

The last submitted patch, 2: 2148255-firstpass.patch, failed testing.

jhodgdon’s picture

Hm. The 2nd pass patch passed. 1st pass had unrelated failures.

The dreaded Drupal\image\Tests\ImageFieldDisplayTest

This seems to be the most common unrelated test failure, and I see it fairly often. Can we do something about it?

sun’s picture

@jhodgdon: Yes, we can, but that requires debugging data. Next time it happens, make sure to copy the actual test result output into a new bug report with title "Random test failure in ImageFieldDisplayTest" and tag that issue with "Random test failure".

jhodgdon’s picture

Good idea. Test output was still there. Filed
#2191563: Random test failure in ImageFieldDisplayTest

xjm’s picture

This seems like a great idea.

  1. +++ b/core/modules/system/core.api.php
    @@ -0,0 +1,324 @@
    + * @section interfacing Interfacing with the outside world
    + *
    + * - @link menu Routing, page controllers, and menu entries @endlink
    + * - @link form_api Forms @endlink
    + * - @link block_api Blocks @endlink
    + * - @link ajax Ajax @endlink
    + * - @link third_party Integrating third-party applications @endlink
    

    Blocks don't really fit in this category to me. They belong more with other site building APIs like Views, nodes, fields, and entities.

  2. +++ b/core/modules/system/core.api.php
    @@ -0,0 +1,324 @@
    + * - @link config_state Configuration and State system @endlink
    

    I think this should be "Configuration and State systems" (plural)?

  3. +++ b/core/modules/system/core.api.php
    @@ -0,0 +1,324 @@
    + * @section utility Utility APIs
    

    I'm not sure "Utility APIs" works as a label for these. We have a utility namespace in components which is totally different stuff.

  4. +++ b/core/modules/system/core.api.php
    @@ -0,0 +1,324 @@
    + * @section advanced Advanced topics
    ...
    + * - @link migration Migration @endlink
    

    I don't think "Migration" should be an advanced topic. Every module owner will need to use the Migration API.

jhodgdon’s picture

FileSize
9.48 KB
1.2 KB

Thanks for the review xjm!

RE item 1 - I think I like where the Blocks API is grouped. The idea there was that if your module was providing a page (routing), block, form, or menu item, that is information "for the outside world" to see, and those topics should be grouped together. That's what we came up with in the brainstorming session... prefer to keep it?

RE item 2 - good catch.

RE Item 3 - we'll need to think of another label... I see your point though. For the moment I changed it to "Other Essential APIs".

RE item 4 - OK. We can move that into the "utiltity" section or whatever it should be called.

Here's a new patch with items 2-4 addressed.

jessebeach’s picture

Status: Needs review » Reviewed & tested by the community

My only hesitation is the topic @section advanced Advanced topics, which feels grab-baggy. But I have nothing better to suggest. Perhaps as this page is reworked and Drupal 8 solidifies, a more natural grouping will suggest itself. Until then, this is a root page that will unblock further work, so let's get it in.

webchick’s picture

Status: Reviewed & tested by the community » Fixed

Awesome work. I think this is a really solid stake in the ground. No doubt we'll be expanding it more later on, re-jiggering where things go as we write out the sub-pages and realize the categories aren't optimal, etc. but the sooner we get this committed, the sooner we can start that work and figure out where things are at. This already provides a much better overview of the architecture changes in D8, so I'm comfortable committing this as-is.

Committed and pushed to 8.x. Thanks!

jhodgdon’s picture

I just made a commit in the Documentation git repo 8.x branch to remove the ancient "index.php" file that was there, which contained the @mainpage.

My next task is to file follow-up issues to fill in the various @todo text for the topic pages. I'll give them all a parent of this issue so... come back in an hour and they should be listed on the issue sidebar.

Status: Fixed » Needs work

The last submitted patch, 12: 2148255-pass3.patch, failed testing.

webchick’s picture

Status: Needs work » Fixed

Yes, yes, testbot.

jhodgdon’s picture

OK, all the child issues have been filed. Phew! Anyone want to write documentation?

I also added this to the Current Docs Priorities page: https://drupal.org/node/1005304 and tweeted it at https://twitter.com/poplarware/status/443833917083090944

eojthebrave’s picture

Ugh. I wrote this review of this patch like a week ago but then somehow failed to post it and just found it sitting in a scratch window in my editor. I kept waiting for a response but they never came ... and now I know why. Oops. :)

Mostly just posting it here for posterity now and because I think there are still a few things we can improve. So, if you would like me to open separate issues for the things I bring up let me know and I'm happy to do so.

--- Slightly dated notes ---

This is awesome, totally needed, and provides a good first step towards making the front page of api.drupal.org more useful. Thanks! Bear with me in my review as this is the first I've really thought about what I would like to see on this page and there's a lot of thinking out loud going on. However, I think this is one of our most important user facing documentation pages so I'm going to ramble a bit. :P

+ * This documentation is generated from specially-formatted comments embedded in
+ * the Drupal source code. Here are some topics to get you started.

Personaly, I would move the bit about documentation generated from source to the end of this first page. It's good to know, but it's not why people are coming to this page.

+ * - @link oo_conventions Object-oriented conventions used in Drupal @endlink

Do we have conventions that are not object oriented that are going to be worth talking about here? Like for example the convention is to use unique names for modules for namespacing purposes, or other things I'm not thinking of right now?

+ * - @link best_practices Best practices @endlink

I think we should change this to "Standards and best practices". Standards = use camelCase for class names and best practices = using the t() function to translate any user facing strings.

+ * @section interfacing Interfacing with the outside world

It wasn't immediatly obvious to me what this heading meant and I had to read through the list of linked resources. And then I still wasn't quite sure if this was about "Interfacing with users" or "Interfacing with other systems.". My recommendation here would be to move the 3rd party apps integration to the other essentials part and to move the theme system to this section. I'm sure it's not always the case but my gut says more people are going to need to know about the theme system than about integrating with 3rd party APIs to lets give it more importance by bringing it higher in the list and grouping it with the other common "I'm trying to display something for the user" topics.

Hmm, now that I type that all out though I realize that the 3rd party integration line could be about creating REST services so that 3rd party apps can consume drupal's data rather than drupal consuming data from 3rd party apps which is how I initially read it. Perhaps we could change that line to something like, "Creating RESTful web services" or something that's a little bit clearer about what you can expect to find when you click that link.

Honestly, Ajax seems like more of an advanced topic to me, but also fits nicely within the context of displaying things on the page. Just kind of thinking out loud on that one. :)

Should we have a link to something about security somewhere in this list? Seems like an important topic. Perhaps this gets covered under best practices. Though it might be important enough that it's worth pulling out to it's own top level item.

Finally, something that I've experienced in years of teaching people Drupal is that developers often times have no idea that Drupal includes helper functions that effectively replace some of the built in PHP functions. format_date(), drupal_strtolower() and their ilk. I think we should include a section about these "helper" functions in the other essential APIs section.

FWIW, I only really reviewd the list of topics since all the sub-sections are just "@todo - write me" right now.

jhodgdon’s picture

Yeah, we kind of decided to just get it in and then work on improvements. At least as it stands, people will have an idea of what the important topics are in D8... it's up on api.drupal.org now. :)

So, yes, let's file a separate issue for your follow-ups. I think we can have one issue for "Improve the landing page", and if you can make a list of what your final recommendations are (or a patch?) then we can go forward with that. Thanks!

And by the way, some similar concerns were raised above, and I doubt I would disagree with any of your recommendataions... but we couldn't think of better names for some of the sections, so they went in as they were until we could think of better ways to organize/name stuff. At least for the moment we have the skeleton there and can start working on the topics! But yes, let's make it even better with a separate issue.

jhodgdon’s picture

Title: Make better D8 api.d.o landing page and put it in Core » [meta] Make better D8 api.d.o landing page, linked to high-level overview topics, and put it in Core api.php files
Issue summary: View changes
Status: Fixed » Active

After brief discussion with webchick in IRC, I've just spun off a child issue:
#2218027: Improve the D8 api.d.o landing page
Let's discuss improvements there. Also, I've turned this into a "meta" issue since it now has all those child issues, with slightly revised issue title, and am going to leave its status as "Active" until all the child issues are resolved.

The reason for doing this is that we've already published this link as the place to go to help out with all the "fill in the docs" child issues, so we'd like to keep this issue open without actually working on a second patch here.

Updated the issue summary to explain what's going on.

jhodgdon’s picture

I'm wondering if we need to add links for the Queue and Batch systems to the api.d.o landing page? We have topics already... Do they belong on the landing page?

webchick’s picture

Wouldn't hurt, I don't think. As long as they're "below the fold" since they're fairly specialized APIs.

jhodgdon’s picture

webchick’s picture

As a current status, looks like 11 of these are fixed, 15 to go (~42%). Go, jhodgdon, go! :)

webchick’s picture

9 left now. :)

jhodgdon’s picture

Well, I just added a new one. Somehow we didn't have an issue filed for the half-baked menu/routing topic. Oops.

webchick’s picture

Woot, I believe we are now officially down to just one more! #2216555: Fill in @defgroup/topic docs for Migration overview Thanks SO much Jennifer!

webchick’s picture

Priority: Normal » Major
Status: Active » Fixed
Issue tags: +beta target

Hells to the yeah! :D Jennifer, remind me to build you a statue next time we meet! Thanks so much to the other subsystem maintainers for their help as well! This is a huge win.

jhodgdon’s picture

Annnnnnd, there was much rejoicing! Thanks for all the reviews/commits everyone -- so glad this is completed! I suppose there will be some followups as APIs are still changing, but at least we have the topics covered.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.

eojthebrave’s picture

This makes me so happy. Thanks for all the hard work that everyone (especially jhodgdon) has helped put into making this happen. Yay!