BigCommerce for Wordpress (BC4WP) Documentation Update

Andrea Dao

Attention all Wordpress developers! We’ve released a v1 documentation for BigCommerce for WordPress plugin: https://bc-wordpress-reference.vercel.app/.

We’ve autogenerated the documentation from the BigCommerce for Wordpress plugin source code. This article provides a clear overview of the streamlined workflow to help those contributing to our docs share feedback on how to further simplify the update process. Our goal is to make contributions smoother and more efficient for everyone.

For a quick overview of how we autogenerate the docs, watch this 3-step video:

What we changed & why

We revamped the workflow for generating documentation to make it more automated and transparent. This new approach simplifies how we produce and maintain documentation, ensuring it's always accurate and up to date. Below are some more details on the changes: 

Github workflow and parsers

The new GitHub workflow for generating documentation is designed to automate the generation and publication of PHP documentation for the BigCommerce for WordPress plugin. It is manually triggered as a Github Action, giving the team control over when we want to generate documentation updates (e.g. only if you update docblocks, rather than every push to the source code).

The key tools include the following and rely on docblocks from the source code:

  1. Pronamic WP Documentor: Parses and generates documentation for WordPress hooks (actions and filters). The forked version of this tool that the workflow uses customizes the parser and adjusts the template to work with the BigCommerce for WordPress repository. 

  2. phpDocumentor: Parses PHP classes, their methods and properties, and standalone functions from doc. 

  3. phpDocumentor-markdown: Extends phpDocumentor to output Markdown files with templates for PHP classes, methods, properties, and standalone functions. The forked version of this tool adds standalone function support to the Markdown template.

The documentation generation script, generate-docs.sh, processes the source code under the src/ directory and outputs a unified documentation set under the `docs/` directory in Github’s virtual runner environment. 

Separate Documentation Repository

The workflow syncs the output to the bc-wordpress-reference repository, where Nextra renders the Markdown files into a fully functional site. The generated Markdown files that the parsers generate are compatible with Nextra, which automatically reads the folder structure that the phpDocumentor creates to autogenerate a menu for the documentation site. 

There are several advantages to storing the documentation in a separate repository from the codebase:

  • Keeps the main codebase clean and independent of the output documentation.

  • Enables distinct hosting and deployment strategies.

  • Supports modularity and maintainability of the project.

Branch-Based Updates

Documentation updates are published to timestamped branches, which indicate when the documentation was generated. For instance, a branch named `docs-2024-12-01_12-30-00` would indicate documentation generated on December 1, 2024, at 12:30 PM. 

This approach:

  • Facilitates a structured review process before merging changes.

  • Simplifies rollback in case of errors.

  • Improves how you can trace updates for version control.

Before merging to the main branch, you can preview the generated documentation in Vercel for accuracy.

File Synchronization

The workflow uses `rsync` to synchronize files efficiently, copying only changed files while maintaining file attributes. This method reduces the time and resources required for publishing documentation while ensuring consistency in the output.

Error Handling

If no changes are detected, the workflow exits gracefully, avoiding unnecessary commits. Detailed error outputs are provided during failures, including the current Git status and branch for debugging purposes.

Manual Triggering

The workflow is triggered manually to avoid unnecessary documentation rebuilds, saving GitHub Actions minutes and granting precise control over when updates occur.

Want to contribute to the BC4WP Documentation?

The Developer Experience team is always in the process of improving our docs and how they are autogenerated.  

Your feedback is invaluable. By sharing feedback on the workflow, you can help ensure the contribution process is as seamless and efficient as possible, making it easier for you to contribute and improve the documentation together. To provide feedback, post a Github Discussion and a team member will get back to you.

To contribute to the docs, see the CONTRIBUTING.md file. 

You can also report issues or improve the parsers visiting the following: