WordPress.org

Making WordPress.org

Opened 3 months ago

Last modified 2 months ago

#5942 reopened enhancement

DevHub: Support viewing source on GitHub mirror

Reported by: netweb Owned by: dd32
Milestone: Priority: normal
Component: Developer Hub Keywords: needs-patch
Cc:

Description (last modified by netweb)

Currently when looking up references in devhub links to the source only link to Trac source, it would be great to add support to also link to the GitHub mirror.

For example, looking at https://developer.wordpress.org/reference/functions/add_theme_support/#source, there is a link to the Trac source at:

https://meta.trac.wordpress.org/raw-attachment/ticket/5942/meta-5942-1.png

And it would be great to also link to the GitHub mirror source at:

https://meta.trac.wordpress.org/raw-attachment/ticket/5942/meta-5942-2.png


A quick look at the code, here's an initial quick patch duplicating the existing get_source_file_link() function:

  • wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/template-tags.php

    diff --git wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/template-tags.php wordpress.org/public_html/wp-content/themes/pub/wporg-developer/inc/template-tags.php
    index 58cfadba4..78daa8e92 100644
    namespace DevHub { 
    11801180                return esc_url( $url );
    11811181        }
    11821182
     1183        /**
     1184         * Retrieve the URL to the GitHub source file and line.
     1185         *
     1186         * @param null $post_id     Post ID.
     1187         * @param bool $line_number Whether to append the line number to the URL.
     1188         *                          Default true.
     1189         * @return string Source file URL with or without line number.
     1190         */
     1191        function get_github_source_file_link( $post_id = null, $line_number = true ) {
     1192
     1193                $post_id = empty( $post_id ) ? get_the_ID() : $post_id;
     1194                $url     = '';
     1195
     1196                // Source file.
     1197                $source_file = get_source_file( $post_id );
     1198                if ( ! empty( $source_file ) ) {
     1199                        $url = 'https://github.com/WordPress/wordpress-develop/blob/' . get_current_version() . '/src/' . $source_file;
     1200                        // Line number.
     1201                        if ( $line_number = get_post_meta( get_the_ID(), '_wp-parser_line_num', true ) ) {
     1202                                $url .= "#L{$line_number}";
     1203                        }
     1204                }
     1205
     1206                return esc_url( $url );
     1207        }
     1208
     1209
    11831210        /**
    11841211         * Compare two objects by name for sorting.
    11851212         *
  • wordpress.org/public_html/wp-content/themes/pub/wporg-developer/reference/template-source.php

    diff --git wordpress.org/public_html/wp-content/themes/pub/wporg-developer/reference/template-source.php wordpress.org/public_html/wp-content/themes/pub/wporg-developer/reference/template-source.php
    index 7f83fb36e..4c1cab14d 100644
    if ( ! empty( $source_file ) ) : 
    3030                                        <a href="#" class="less-complete-source"><?php _e( 'Collapse full source code', 'wporg' ); ?></a>
    3131                                </span>
    3232                                <span><a href="<?php echo get_source_file_link(); ?>"><?php _e( 'View on Trac', 'wporg' ); ?></a></span>
     33                                <span><a href="<?php echo get_github_source_file_link(); ?>"><?php _e( 'View on GitHub', 'wporg' ); ?></a></span>
    3334                        </p>
    3435                <?php else : ?>
    3536                        <p>

Attachments (2)

meta-5942-1.png (191.1 KB) - added by netweb 3 months ago.
meta-5942-2.png (202.1 KB) - added by netweb 3 months ago.

Download all attachments as: .zip

Change History (13)

@netweb
3 months ago

@netweb
3 months ago

#1 @netweb
3 months ago

  • Description modified (diff)
  • Keywords needs-patch added
  • Type changed from defect to enhancement

#2 @dd32
3 months ago

  • Owner set to dd32
  • Status changed from new to accepted

#3 @netweb
3 months ago

p.s: Props to @stuartshields for the idea

#4 @dd32
3 months ago

  • Resolution set to fixed
  • Status changed from accepted to closed

In 11311:

Code Reference: Include a link to view the source on GitHub.

Props stuartshields, netweb, dd32.
Fixes #5942.

#5 @dd32
3 months ago

I added the end line number to the link too, so that it highlights the entire function: https://github.com/WordPress/wordpress-develop/blob/5.8/src/wp-includes/post-template.php#L243-L256

Oh, and uh removed the $line_number arg since well, it didn't do what it said it does on the box, and isn't used anywhere.

Last edited 3 months ago by dd32 (previous) (diff)

#6 follow-up: @dd32
3 months ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

This only applied to functions and not other locations, like hooks: https://developer.wordpress.org/reference/hooks/comment_text/

The above hook also shows a parser bug, as it's unable to extract the PHP for the hook, this affects a number of hooks and functions that I've seen over the last few months.

#7 in reply to: ↑ 6 ; follow-up: @coffee2code
3 months ago

Replying to dd32:

The above hook also shows a parser bug, as it's unable to extract the PHP for the hook, this affects a number of hooks and functions that I've seen over the last few months.

Hooks are (and have always been) explicitly excluded* from having their PHP source shown since doing so is not meaningful (it'd just be a duplicate of the hook definition at the top of the page), so it merely links to the source.

Functions should always show their source code though, so I'd be happy to look into any that are failing to do so.

This only applied to functions and not other locations, like hooks:

Following on from my explanation above, the change made by the patch to reference/template-source.php needs to also be applied in the nearby else.


* In the template reference/template-source.php, which uses post_type_has_source_code() which uses get_post_types_with_source_code().

#8 in reply to: ↑ 7 ; follow-up: @dd32
3 months ago

Replying to coffee2code:

Replying to dd32:

The above hook also shows a parser bug, as it's unable to extract the PHP for the hook, this affects a number of hooks and functions that I've seen over the last few months.

Hooks are (and have always been) explicitly excluded* from having their PHP source shown since doing so is not meaningful (it'd just be a duplicate of the hook definition at the top of the page), so it merely links to the source.

Huh, you're right.. okay that certainly makes sense.

Kind of seems weird that the source-code for the hook isn't displayed within the "Source" heading though, given it's only a single line usually, it might be worth duplicating it there?

Functions should always show their source code though, so I'd be happy to look into any that are failing to do so.

twenty_fourteen_ephemera_widget::__construct and similar theme class methods are probably a good example, I'm sure I've seen another one but I can't think of it off the top of my head.

the class definition doesn't even exist

#9 in reply to: ↑ 8 ; follow-up: @coffee2code
3 months ago

Replying to dd32:

Kind of seems weird that the source-code for the hook isn't displayed within the "Source" heading though, given it's only a single line usually, it might be worth duplicating it there?

For consistency and completeness, I wouldn't be opposed to having the line of code for each hook to be included. I can include them in the parsing of 5.8.2 (at the latest) when it lands, or sooner if I get a chance. It requires a CLI run to pre-cache source code after a necessary code adjustment has been committed.

twenty_fourteen_ephemera_widget::__construct and similar theme class methods are probably a good example, I'm sure I've seen another one but I can't think of it off the top of my head.

Ah, thanks. Those shouldn't exist and have been deleted. In the early days of the Code Reference, parsings included bundled themes, but were quickly deemed not to be included. Much of those parsed theme resources had since been deleted. Looks like a handful of methods (including the one you mentioned) and a couple hooks still persisted, but are gone now.

So I'm not surprised that with those methods existing that their source codes were understandably missing. However, any legitimate functions/methods/classes should have the proper source code embeds.

the class definition doesn't even exist

As noted, this is the proper situation since theme-specific data shouldn't exist.

#10 in reply to: ↑ 9 @dd32
3 months ago

Replying to coffee2code:

So I'm not surprised that with those methods existing that their source codes were understandably missing. However, any legitimate functions/methods/classes should have the proper source code embeds.

I went and dug up some more examples:
https://developer.wordpress.org/reference/classes/wp_matchesmapregex/wp_matchesmapregex/
https://developer.wordpress.org/reference/classes/wp_customize_custom_css_setting/validate_equal_characters/
https://developer.wordpress.org/reference/classes/ixr_server/multicall/
https://developer.wordpress.org/reference/functions/upgrade_101/

I'll DM you on slack with a SQL query to pull up the 175 items.

This ticket was mentioned in Slack in #meta by tellyworth. View the logs.


2 months ago

Note: See TracTickets for help on using tickets.