A Developer resources site before the 5.0.0 release?

During our latest dev-chat, we’ve been talking about putting together a documentation site for the BP REST API. I’ve been exploring the subject more deeply this week and I believe we should take this opportunity to try to ship a first version of the developer resources site.

I think 5.0.0 is an interesting time/release (as it’s a very developer oriented one with the inclusion of the BP REST API) to start powering BuddyPress developers with some resources just like WordPress does with its DevHub project.

The « BP » DevHub project?

@tw2113 started working on a BuddyPress Code Reference site 3 years ago, see #6812. In his last comment he expressed his concern about the lack of developer content the site would offer. Then I thought the BP REST API documentation could be a great companion to this BuddyPress Code Reference! So I’ve carried on his work and built a local test site to check how difficult it could be to make this real.

Preview of the homepage of the Developer resources site.

It’s doable before the 5.0.0 release!

It took me a couple of days, following and adapting the installation steps described in this chapter of the WordPress Documentation handbook, to build a « proof of concept » framework. Actually all I had to do was to create a child theme for the « wporg-developer » theme and share 2 patches on the Meta Trac (see #4516 & #4517) so that the Meta Team could fix the 2 issues I’ve found during my explorations.

Here’s what we need to do on the existing developer.buddypress.org site :

1. Make sure Composer and WP CLI are running on the server.
2. Install the « wporg-developer » theme.
3. Install the WP Parser plugin → composer create-project wordpress/phpdoc-parser:dev-master --no-dev & activate it.
4. Install & activate the Syntax Highlighter plugin.
5. Install/Build the latest version of BuddyPress 😍 (no need to activate it).
6. Run the WP CLI command using the BuddyPress directory of point 5 as the argument. For example: wp parser create path/to/wp-content/plugins/buddypress --user=1 or wp parser create path/to/wp-content/plugins/buddypress/build --user=1 if trunk is used.
7. Install & activate the Handbook plugin (We don’t need the wporg-markdown & wporg-cli plugins as we don’t write our documentation on GitHub and moreover it would import the WordPress REST API and Coding standards documentations).
8. Install & activate the « bporg-developer » child theme I’ve built using the Customizer live preview (so that it automatically creates the starter content – make sure the fresh_site option has its value set to 1).
9. Go to the General Settings Administration screen and insert the version of BuddyPress into the BuddyPress latest stable version option.

• 

• 

• 

Wait, but what about the BP REST API Documentation?

If you’d go on the BP REST API Handbook at this stage you wouldn’t see any content. We need to create it. We chose to have it generated thanks to the REST schemas of our REST endpoints. The Restsplain plugin does this task for all the WordPress and custom endpoints of the website.

Using it as it would first mean to activate BuddyPress (and possibly the BP REST plugin if not yet included into BuddyPress).

There are benefits of having the generated documentation this way as new endpoints would automatically be included. It’s also possible to create and attached content to our endpoints using the post type included inside the plugin. But there are also disadvantages: 

• All BuddyPress components would need to be activated.
• The React Application inside the Restsplain plugin is displaying the real URLs at various places.
• It is also including a feature to use them into a specific container to make real REST requests.

The good new is: we can filter the list of endpoints the Restsplain plugin is generating. So I’ve added this filter to the bporg-developer theme and the documentation generation is now restricted to BuddyPress endpoints. Then I thought we could avoid the need for BuddyPress to be activated by first looking for an external Json file (a static copy of the array expected by Restsplain, where links are « anonamisized »).

But still, I had to remove completely the live testing of endpoints feature. Although it can be done in CSS, I chose to edit the plugin because:

• it has not been updated for 7 months and as a result contains outdated node modules and React library.
• Some real links are built in React using the rest base URL.
• One of the link of the React endpoint viewes is triggering the live testing.

As a result the version of the plugin I suggest to use is the fork I’ve made here. As I’ve edited the React part, I also edited the styles to match the BuddyPress.org colors. Here’s how it looks:

As you can see it’s very different from the output made by the WordPress handbook plugin. The best I could do to make it more looking like it was to use the [restsplain] shortcode in a page.

That’s why I think we should probably only use this plugin to write a static version into the BP REST API handbook post type of what it generates dynamically.

We have 14 endpoints to document for 5.0.0 and 8 others for the 6.0.0 release and I think we can do some copy/pasting:  it won’t take too much time and the layout of the documentation will be the same for every potential handbooks (eg: BuddyPress plugins or themes).

Moreover we’ll be able to improve the navigation grouping endpoints by components, we’ll be able to use more meaningful titles for the GET, POST, PATCH, DELETE methods, eg: Get a specific user, add a user, update a user and remove a user. Finally we would be able to use code examples using our bp.apiRequest function instead of the fetch function Restsplain uses. Below is a screenshot showing what I mean about this copy/pasting task.

What if we’re running out of time building the developer resources site?

It would be too bad, but not a so much big deal! I’ve already created a documentation site for the BP REST API. You can test it here. We would simply need to attach to this site a more meaningful domain name 😉

And when/if we get the developer.buddypress.org site ready (See the 9 steps above) soon enough we’ll be able to use this website to do the copy/pasting tasks.

Let’s discuss about it during our next dev-chat!

As a reminder, it will happen this Wednesday (June 26) at 19:00 UTC into our Slack channel: #BuddyPress. All BuddyPress Contributors are very welcome to join us. If you’re a bit intimidated (you shouldn’t!) but still want to give us your opinion about this topic, please use the comments area below 👍

#5-0, #developer-documentation