BP-CLI - How to handle placement within the Docs folder (Handbook or Chapter)

[emaralive]

During the February 28, 2024 Docs-Chat meeting, @renatonascalves brought up a requirement to include BP-CLI documentation.

This topic provides a vehicle in which further details can be explained/discussed to determine whether a handbook or a chapter would be apropos (appropriate), One point of reference that was used as a requirement during chat was:

WP-CLI Commands

That stated, @renatonascalves, you have the floor to present your requirements in further detail.

[renatonascalves]

Thanks! So, let me elaborate a little bit on what we are trying to do and how.

BuddyPress has a bunch of CLI commands: https://github.com/buddypress/wp-cli-buddypress Those commands are bundled with BuddyPress when we release a new version. But they are also available via composer.

The goal is to have an area in the Developer site (https://developer.buddypress.org/) for the BP CLI commands. Similar to the one from WP core: https://developer.wordpress.org/cli/commands/

The way WordPress core's approaching this happens as follow:

• Command pages are generated dynamically from the WP-CLI codebase using the wp handbook series of commands. See here for the commands.
• After the pages are created, in .md files, they are saved to this repo.
• Then, all documentation is imported automatically into WordPress.org in a two step process:
  • WordPress.org reads this file: https://github.com/wp-cli/handbook/blob/main/bin/commands-manifest.json to understand all pages that need to be created.
  • Each WordPress page has a markdown_source attribute specifying a Markdown file to be fetched, converted to HTML, and saved in the database.
  • Here is the code for this functionality.
  • Here it is in the new theme.

---

I'm proposing we do something similar:

• The BP CLI documentation will be manually generated at every BuddyPress release;
  • We need to create a custom command to generate dynamically the command pages;
• Those pages will be hosted on https://github.com/buddypress/wp-cli-buddypress as per @imath's suggestion. In a docs folder.
  • This folder won't be bundled into https://github.com/buddypress/buddypress when releasing a new version.
• Then, all documentation will be imported automatically into developer.buddypress.org in a similar process WordPress uses today.
  • We will need to add a custom implementation to handle our use case. We have prior art from WP core.

The main benefits of this approach are:

• The documentation will be consistent with the installed software;
• We only need to update it when we release a new BuddyPress version AND if necessary;
  • It's possible that in a release, no changes were performed in the BP CLI, so no need to update it.
• Similarly to the code reference, most of the process will be automated;

[renatonascalves]

I reached out to the #meta-debhub so that we have someone that can help us merge this into core. See here.

[emaralive]

I'm just now catching up to previous activities and it doesn't look like there has been a public response to your message in the #meta-debhub channel. I'm not sure but it seems like there postings of issues & pull requests: meaning, there doesn't appear to be active conversations that occur regularly.

I'm wondering if the conversations are occurring in the #docs channel and it looks like there will be a meeting on March 5, 2024 @ 2 PM UTC. For me, it's all a bit confusing and the learning curve is a bit steep due to my unfamiliarity with all the given processes involved with documentation creation.