Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 UTC on 18 March 2024, to get $100 off your ticket.
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.
Comment | File | Size | Author |
---|---|---|---|
#12 | interdiff.txt | 1.2 KB | jhodgdon |
#12 | 2148255-pass3.patch | 9.48 KB | jhodgdon |
#4 | apilanding.png | 40.93 KB | jhodgdon |
#3 | interdiff.txt | 1008 bytes | jhodgdon |
#3 | 2148255-secondpass.patch | 9.47 KB | jhodgdon |
Comments
Comment #1
jhodgdonIt's time to do this... I will take it on.
Comment #2
jhodgdonHere'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.
Comment #3
jhodgdonI 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?
Comment #4
jhodgdonHere'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.
Comment #5
jhodgdonAssigning 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...
Comment #8
jhodgdonHm. 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?
Comment #9
sun@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".
Comment #10
jhodgdonGood idea. Test output was still there. Filed
#2191563: Random test failure in ImageFieldDisplayTest
Comment #11
xjmThis seems like a great idea.
Blocks don't really fit in this category to me. They belong more with other site building APIs like Views, nodes, fields, and entities.
I think this should be "Configuration and State systems" (plural)?
I'm not sure "Utility APIs" works as a label for these. We have a utility namespace in components which is totally different stuff.
I don't think "Migration" should be an advanced topic. Every module owner will need to use the Migration API.
Comment #12
jhodgdonThanks 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.
Comment #13
jessebeach CreditAttribution: jessebeach commentedMy 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.Comment #14
webchickAwesome 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!
Comment #15
jhodgdonI 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.
Comment #17
webchickYes, yes, testbot.
Comment #18
jhodgdonOK, 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
Comment #19
eojthebraveUgh. 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
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.
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?
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.
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.
Comment #20
jhodgdonYeah, 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.
Comment #21
jhodgdonAfter 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.
Comment #22
jhodgdonI'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?
Comment #23
webchickWouldn't hurt, I don't think. As long as they're "below the fold" since they're fairly specialized APIs.
Comment #24
jhodgdonOK, filed novice issue #2265851: Add link to Queue and Batch APIs on api.drupal.org D8 landing page as child of this one.
Comment #25
webchickAs a current status, looks like 11 of these are fixed, 15 to go (~42%). Go, jhodgdon, go! :)
Comment #26
webchick9 left now. :)
Comment #27
jhodgdonWell, I just added a new one. Somehow we didn't have an issue filed for the half-baked menu/routing topic. Oops.
Comment #28
webchickWoot, I believe we are now officially down to just one more! #2216555: Fill in @defgroup/topic docs for Migration overview Thanks SO much Jennifer!
Comment #29
webchickHells 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.
Comment #30
jhodgdonAnnnnnnd, 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.
Comment #32
eojthebraveThis makes me so happy. Thanks for all the hard work that everyone (especially jhodgdon) has helped put into making this happen. Yay!