Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.This is a follow-up for #2148255: [meta] Make better D8 api.d.o landing page, linked to high-level overview topics, and put it in Core api.php files to discuss improvements that we should make to the new D8 landing page, which you can see on
https://api.drupal.org/api/drupal/8
and which is in the @mainpage doc block in
core/modules/system/core.api.php
Comments
Comment #1
eojthebraveI left some notes in this comment on the issue where this page was initially committed/updated and want to make sure they don't get lost. https://drupal.org/comment/8576691#comment-8576691
Summary:
- Move the comment about docs being generated from code to the bottom of the page.
- Rename the "Interfacing with the outside world" section to something that's easier to grok. Maybe rename it to "User interface" and then move the stuff about interacting with 3rd party application to it's own section.
- Add a link to "Security" somewhere. This is important and should not be buried even though it fits in best practices we want people to see it.
- Add something about Drupal helper functions like format_date and drupal_strlen etc.
Do we think it makes sense to try and add an introductory sentence or two to each of the sections? Kind of a "why you can expect out of this section". A page like this is really accomplishing 2 tasks. It's providing quick access to common documentation topics for users who already know what they are doing and what they want to lookup but just need a refresher. And, providing a roadmap of sorts for people who are just getting started with the documentation and don't really even know where to start. Lets make sure it works well for both of those scenarios.
Comment #2
jhodgdonOh sorry, yes I should have moved those comments over here. Thanks!
So, here are my thoughts on the ideas in comment #1, and I've added (a), (b), etc. so we can refer to them later (you might consider editing comment #1 similarly for easier reference?):
a) "docs generated from the code" line... Maybe we should revise it to say:
Thoughts?
b) "Interfacing with outside world" section... I agree the 3rd-party topic is a bit of a loner... Maybe we could just move that to the "Advanced topics" section, and rename the rest "User interface"? We could also rename "Advanced topics" to be "Other/advanced topics"?
c) Link to security -- That is covered in the (newly committed) Best Practices topic that is in the first section. How about we rename the link "Security and best practices" and maybe move it up right under "Drupal's architecture" in that list?
d) Helper functions... good idea. There's also an existing topic for Sanitization functions https://api.drupal.org/api/drupal/core%21includes%21common.inc/group/san... and one for Formatting functions https://api.drupal.org/api/drupal/core!includes!common.inc/group/format/8 ... So yes, we could make a new landing page for "Utility functions" and link to those two topics inside it? Maybe put that under "Other essential APIs" section? We should also probably add all of the classes in the Utility namespace to this new topic:
https://api.drupal.org/api/drupal/namespace/Drupal!Component!Utility/8 -- a lot of the "helper" functions are now on these classes, and the wrapper functions are I think mostly deprecated in 8.
e) Intros in each section... I don't actually think that is a good idea. Hopefully the headers and links are clear enough, and if not we should change them so they are. The page should be easy to scan.... But I could be convinced if you think there is information that needs to be imparted that cannot be conveyed in a few words. If you have some specific ideas, let's discuss them. Maybe the headers or links just need to be clearer in a few places?
Anyway... Thanks -- want to make a patch? :)
Comment #3
jhodgdonAnd by the way, I think we should spin (d) off into its own issue probably?
Comment #4
eojthebraveI'm fine with Renaming to "Security and best practices" and leaving it where it is. I think you need to know about the other things in this section before you'll really be able to grok best practices.
I did move
* - @link oo_conventions Object-oriented conventions used in Drupal @endlinkUp in the list, re-ordering that section so that things come in a logical order.
I'll also create a new issue for adding a section/link for helper functions.
Comment #5
eojthebraveNew issue here: #2225265: Add utility functions landing page on api.drupal.org linked from main page
Comment #6
jhodgdonThe patch file is empty.
Comment #7
eojthebraveWell that's not very helpful. Lets try that again.
Comment #8
jhodgdonYou know... After looking at this patch, I realize we should not have the line about "official documentation site" in there. The reason is that there are any number of other sites that use the API module to build on-line documentation sites, and they are not "official". So we need to take that out. Sorry, just realized...
I think we could just take out "the official" and replace it with "an", so it would read: "This site is an API reference for...".
Other than that, I think the rest of this patch is fine. Thanks!
Comment #9
eojthebraveGood call. Changed.
Comment #10
jhodgdonLooks fine! Since I think you have an API test site up and running... Did you happen to try out this patch on your site? I'm wondering if the link in
comes out right, or if it scarfs up the . at the end and tries to link to developing/api. instead of developing/api without . ?
Comment #11
eojthebraveThe link works just fine. I was skeptical about it too so actually went through the whole process of setting up an api test site just to make sure it is working.
http://monosnap.com/image/phnGdK1ZvLYUnopGZd376xYF6n4eLp
Comment #12
jhodgdonExcellent, thanks! I of course (being the maintainer of the API module) have an API test site, but it's pretty out of date and it would have taken a while to parse a lot of other files... Anyway, that was my only concern, so this is good to go now.
Comment #13
webchickAwesome, these look like great improvements. :)
Committed and pushed to 8.x. Thanks!