WordPress.org

Making WordPress.org

Opened 5 months ago

Closed 2 months ago

Last modified 2 months ago

#2968 closed enhancement (fixed)

Move REST API Handbook content to GitHub

Reported by: rmccue Owned by: Otto42
Milestone: Priority: normal
Component: Developer Hub Keywords: has-patch commit
Cc:

Description

Much like wp-cli, the REST API documentation would greatly benefit from being on GitHub, and using an open editing process.

I've adapted the existing code used to power the wp-cli commands reference on DevHub into a new generic plugin. The CLI code has been updated to use this, and new API code is added to move our handbook there too. Patch incoming momentarily.

Do not commit this yet. I want to maintain the syncing plugin on GitHub and either pull it in as an svn external instead, or sync it manually.

cc @danielbachhuber

Attachments (5)

2968.diff (23.7 KB) - added by rmccue 5 months ago.
Add WPORG Markdown plugin for CLI/API handbooks
2968.2.diff (20.7 KB) - added by rmccue 5 months ago.
Updated patch with admin UI
2968.3.diff (20.8 KB) - added by rmccue 5 months ago.
Parse Markdown inside shortcodes
2968.4.diff (20.8 KB) - added by rmccue 4 months ago.
Wrap REST API class include in class_exists
2968.5.diff (21.5 KB) - added by rmccue 4 months ago.
Prefix cron actions with devhub_ and ensure schedule is registered

Download all attachments as: .zip

Change History (27)

This ticket was mentioned in Slack in #core-restapi by rmccue. View the logs.


5 months ago

@rmccue
5 months ago

Add WPORG Markdown plugin for CLI/API handbooks

#2 @rmccue
5 months ago

2968.diff adds a new WPORG Markdown plugin that just provides the base class used by the CLI (commands) and REST API handbooks. It doesn't update the CLI Handbook proper to use it yet, since that has a bit more functionality, but it will. Will require the CLI Handbook's manifest to be updated though, since it's incompatible.

In the process of extracting this out, I added a few extra bits of functionality not in the existing classes:

  • Updating existing pages - If an existing page is found, it will now update the source URL. This allows us to retrofit into existing Handbooks (like the REST API)
  • Conditional updates - When fetching the Markdown source, it will store the ETag from the server, and send it back on the next request. GitHub will return a 304 response, allowing us to skip updates altogether.
  • Simplified manifest - Removed the requirement for title and cmd_path from the manifest. title is pulled from Markdown anyway, and cmd_path is redundant with the key already there. (This still correctly parses the CLI command manifest.)

Will also publish this to GitHub as a standalone plugin.

This ticket was mentioned in Slack in #core-restapi by rmccue. View the logs.


5 months ago

@rmccue
5 months ago

Updated patch with admin UI

#5 @rmccue
5 months ago

Added 2968.2.diff which changes the following:

  • Edit Links - Changes admin bar Edit link to point at GitHub, and adds an edit link after the page title for all users.
  • Admin UI - Adds a message to editors who go to the page warning that content/title/slug are synced.
  • No CLI Changes - I removed the CLI command reference changes here, so we can ship for the API handbook without being blocked on compatibility. That said, I still have the changes ready, and it'd be great to switch both (and also the regular CLI handbook) eventually.

I'm personally happy to ship this ASAP, since we want to keep making content changes, and I want to avoid a messy reimport to Markdown (which I did by hand).

@kadamwhite Are you happy for us to switch over? If so, let's wrangle a meta-committer and get this thing shipped.

@rmccue
5 months ago

Parse Markdown inside shortcodes

#6 @rmccue
5 months ago

2968.3.diff allows Markdown inside shortcodes. This is handy for things like [alert], and also works around https://github.com/Automattic/jetpack/issues/7535

#7 @rmccue
5 months ago

  • Keywords has-patch added

#8 @kadamwhite
5 months ago

Going to review this today and then would be down to move forward!

This ticket was mentioned in Slack in #core-restapi by rmccue. View the logs.


5 months ago

This ticket was mentioned in Slack in #core-restapi by rmccue. View the logs.


4 months ago

This ticket was mentioned in Slack in #core-restapi by rmccue. View the logs.


4 months ago

This ticket was mentioned in Slack in #core-restapi by rmccue. View the logs.


4 months ago

#13 @kadamwhite
4 months ago

When this patch is applied the plugin will not be active yet (because it's being added), and if the plugin is not active then we get an error Class 'WordPressdotorg\Markdown\Importer' not found. Should we have a defensive check around this?

#14 @rmccue
4 months ago

Should we have a defensive check around this?

Makes sense to me! I'll update the patch with this.

@rmccue
4 months ago

Wrap REST API class include in class_exists

@rmccue
4 months ago

Prefix cron actions with devhub_ and ensure schedule is registered

#15 @kadamwhite
4 months ago

Patch applies cleanly, works as advertised, and this would be a huge win. +1 from me!

#16 @rmccue
4 months ago

  • Keywords commit added

Let's ship it.

This ticket was mentioned in Slack in #meta-devhub by rmccue. View the logs.


4 months ago

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


3 months ago

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


2 months ago

#20 @Otto42
2 months ago

[5992] Add wporg-markdown plugin from #2968. This does not make it live on w.org yet, this is only preliminary. More commits to follow.

#21 @Otto42
2 months ago

  • Owner set to Otto42
  • Resolution set to fixed
  • Status changed from new to closed

In 5993:

Devhub: Add changes to use wporg-markdown code from developer theme. Props @rmccue, fixes #2968.

This ticket was mentioned in Slack in #core by jeffpaul. View the logs.


2 months ago

Note: See TracTickets for help on using tickets.