Contributing to the Docs

Documentation can be added to pmc-docs either either manually or automatically.

• Manual documentation is added to pmc-docs directly.
• Automatic documentation is extracted/synced from an external source.

Manual documentation

Manual updates would be documentation that is unrelated or independent from a GitHub repository.

• Issue a PR against the pmc-docs (opens in a new tab) repo.
• No review is required and it will automatically deploy to docs.pmcdev.io (opens in a new tab).
• Make sure to take a look at the Nextra Docs (opens in a new tab) for what is supported automatically before adding new features.
• Make sure to update the package.json version.

Automated documentation

Some automation has been added to this repo as a workflow during build time. That automation does one of the following:

• Copies a directory of markdown files.
• Parses directories and auto-generates markdown files based on README files and the contents of PHP classes and javascript files.

Example PRs

• Adding pmc-vvv repo (opens in a new tab)
• Adding boomerang repo (opens in a new tab)
• Adding terraform repo (opens in a new tab)

Supported automation

Several elements of PHP and JavaScript files are automatically parsed and documented, but not all. Supported features include:

• PHP Class files: docBlocks, class docBlocks, class methods, WordPress method filters.
• JS Functions: docBlocks, methods, WordPress filters.

Usage

If the plugin exists as part of the pmc-plugins (opens in a new tab) repo you can only update the cli/commants/generate/index.js file.

If the project does not exist as part of the pmc-plugins (opens in a new tab) repo, you must

1. Add the checkout to the .github/workflows/publish-docs.yml file.
2. Add the npm run docs generate command defining the source option referencing the repo.
3. Then create a custom runner which will define which files/directories need to be handled.
4. If the project is a private repository, to use the PMC_GITHUB_ACTION_SSH_KEY, ensure that repository has been added to the read-only user's accessible repositories (example (opens in a new tab)).

Example

 - name: Checkout source repository
      uses: actions/checkout@v3
      with:
        repository: penske-media-corp/repo-name
        ssh-key: ${{ secrets.PMC_GITHUB_ACTION_SSH_KEY }}
        ref: main
        path: repo-name
 
 - name: Copy files to docs.
      run: |
        npm run docs generate -- --source=repo-name

Several functions exist to help find files/directories and copy or parse its contents:

getNonHiddenFolders

Get non hidden folders for a given directory.

• source: string — directory pathname.

getNonHiddenFiles

Get non hidden files for a given directory.

• source: string — directory pathname.

getFilesAndFolders

Gets non hidden files and folders for a given directory.

• source: string — directory pathname.

getRelativePath

Forms a relative pathname relative to the root pmc-docs directory.

• source: string — directory pathname.

// Output example: ...[path to root]/wp-content/plugins/pmc-docs/pages.
getRelativePath('/pages')

processDirectory

Process a single directory.

• source: string — directory source pathname.
• output: string — directory output pathname.

processDirectory(
 `${source}/${folder}`,
 getRelativePath(`/pages/core-tech/gutenberg/${folder}`)
);

copyDirectoryContents

Copy the entire source of a directory wholesale to a destination.

• source: string — directory source pathname.
• output: string — directory output pathname.
• excludeDirectories: array — array of directories to exclude.
• excludeFiles: array — array of files to exclude.

copyDirectoryContents(
 `/docs`,
 getRelativePath('/pages/core-tech/gutenberg'),
 ['directory-name'],
 ['file-name.mdx']
);

copyFileContents

Copy a single file from one location to another.

• source: string — directory source pathname.
• output: string — directory output pathname.

copyFileContents(
 `/docs/file-name.mdx`,
 getRelativePath('/pages/core-tech/gutenberg/file.mdx'),
);

Testing Locally

Automating this process may be handled in a future update. It is currently more manual.

• Clone the pmc-docs (opens in a new tab) repo locally.
• Run the npm run docs generate -- --source= where the source option is the relative path location of your working pmc-plugins repo (or repo you're generating docs for). For example: npm run docs generate -- --source=/Users/USERNAME/vvv-local/www/variety-com/public_html/wp-content/plugins/pmc-plugins
• Run npm run start to run docs locally at http://localhost:3000 (opens in a new tab).