Source code should display on individual pages

[samuelsidler]

Individual pages should display the source code.

​individual function pages.

This will be similar to the approach that Rarst has taken on Query Posts: ​http://queryposts.com/function/get_bloginfo/

[Rarst]

Are we link to external source viewer or inline (QP style)?

[samuelsidler]

Replying to Rarst:

Are we link to external source viewer or inline (QP style)?

I'd say whatever's easiest right now (probably a link to core trac viewer), with a new ticket on file to see if we should do it inline in the future.

[siobhan]

I'm changing this priority to high and assigning to Rarst. The source code should be visible on individual pages

[SergeyBiryukov]

#454 was marked as a duplicate.

[atimmer]

176.diff adds a naive implementation of source code displaying on individual pages.

What should at least be added:

• Syntax highlighting, I tried to add this but the syntax-highlighter plugin (that is used in the handbook) doesn't have any filters to add the script, neither does it use wp_register_script, it is also impossible to modify the object because they create it in the file itself and don't assign it. A possible solution would be a different plugin (but no compat with the handbooks) or including the script ourselves on the correct pages (If the plugin moves the script the syntax highlighting breaks)
• Partial showing of code, right now the whole piece of code is shown. On page load you should see a short version and with a button you should be able to see all the text, preferably with a nice javascript animation.

[atimmer]

176.2.diff adds syntax highlighting and showing only 200px and expanding after.

I don't know how you compile the scss to css so I put the style inline for now.

For the syntax highlighting you need to install and activate the ​Syntax Highlighter MT plugin, I am guessing it is the same plugin as the handbooks. The plugin I used before isn't updated in 2 years so I guess that is not the one used on the handbooks.

[kpdesign]

Replying to atimmer:

For the syntax highlighting you need to install and activate the ​Syntax Highlighter MT plugin, I am guessing it is the same plugin as the handbooks. The plugin I used before isn't updated in 2 years so I guess that is not the one used on the handbooks.

All of the handbooks and Make sites use the SyntaxHighlighter Evolved plugin: ​http://wordpress.org/plugins/syntaxhighlighter/

Will your patch work with that plugin?

[atimmer]

This new patch 176.3.diff works with the SyntaxHighlighter Evolved plugin. It also adds the styles to the scss and css files. This assumes #477 is fixed.

[coffee2code]

Great work and I like how it looks and operates on the front-end.

However, we need to be mindful of performance. We can't do full file, in-memory loading of source files on every request. Ideally the source code would be parsed and stored by the parser (maybe as postmeta or a special comment). On-the-fly isn't the way to go with this, especially without caching the results. Naturally since the parser doesn't currently do this, this general approach was necessary.

Regarding 176.3.diff​ and putting aside how the function source code is obtained, here are some things I noted:

• If the full, un-syntax highlighted source is shown (JS disabled, SyntaxHightlighter not enabled, etc), the "Show complete source code" link appears. That link should be hidden by default and shown via JS since the non-JS view (rightly) shows the full source code anyhow.
• For short functions, e.g. __return_false(), things don't act as desired:
  • The "Show complete source code" link appears even though the function is fully visible.
  • The source code div is given a height of 186px, which is more space than needed for some short functions. The height should ideally be shorter in such cases.
• When the link is clicked, the full display of the function does not include the ending line (the function's closing brace). For short functions already fully shown, that line gets removed from the view.
• Regarding the link text "Show complete source code":
  • Instead of "complete", I'd recommend "full" or "entire". Using "complete" has the connotation that what is being viewed currently is in-progress and unfinished.
  • The 'New in' widget at /reference uses "View all…". If we want to consider keeping the syntax for the two similar, maybe this string should be "View full source code…" or "View entire source code…".
• With relative ease you can extend support to wp-parser-method as well.

I have an idea to adapt get_source_code() to use stored data, and to prime the storage of that data. While the parser could do it (which we'll eventually file a ticket for) it can be made to work even if the parser doesn't help. I'll follow up shortly. Addressing the things I noted above in the meantime would be great though, just leave get_source_code() as-is and I'll adapt that.

[coffee2code]

FYI: As @samuelsidler suggested earlier, there exists #447 as an intermediate solution that can be more easily implemented: a simple link to core.trac to the relevant function. Though as Rarst does on QP, we would still likely link to core.trac even with in-line source.

[atimmer]

Added 176.4.diff with the changes you suggested. In the end I liked "View full source code…" the best.

[coffee2code]

In 676:

Code Reference: Add inline source code display for functions and methods. props atimmer. See #176

[coffee2code]

In 677:

Code Reference: Improvements to inline source code display. Fixes #176

• More efficient implementation of get_source_code()
• Add get_source_code_root_dir() which gets 'wp_parser_root_import_dir' option value if set by parser, else ABSPATH
• Add post_type_has_source_code()
• Use 'wporg' as the text domain
• Slight tweak to JS height comparison to ensure functions that just fit don't trigger expansion handling
• Allow x scrollbar for .source-code-container and adjust heights to account for its possible display
• Add extra height to collapsed state of .source-code-container to partially show the first hidden line to better indicate there is more code
• Add right border to .source-code-container so it is easier to tell if code is being clipped
• Change 'View source' link to 'View source code:' label with explicit links to inline source and/or WP Trac code browser
• Source code is stored in post meta; parse and store it as requested if it isn't
• Sanity check to ensure proper conditions exist for parsing
• Add optional 'force_parse' arg to get_source_code() to force reparsing of source file

[coffee2code]

In 687:

Code Reference: Improve linking related to source code display. See #176

• Remove 'View source code:' label and links
• Add 'View source' link that links downpage to Source section
• Remove ellipsis from link text
• Add ability to collapse expanded source code
• Move link to core.trac for function to be under source code display as 'View on Trac'
• Fix to display link to trac for hooks and classes