[docs] Migrate the Plugin_files page

[andrewnicols]

No description provided.

[andrewnicols]

This issue needs a bit of explaining.

As I was moving some of the plugintype doumentation over I noticed that there is a lot of documentation relating to plugin files which is duplicated, or out-of-date. We often document files like version.php in plugintype docs, but each is different, with different levels of detail, etc.

To solve this I thought it would be useful to move these sections out into reusable templates, but then I realised that we sometimes want to specify extra information, differnt information, different examples, no examples, etc.

To solve this I created a ComponentFileSummary component which takes the key information required to generate a summary of a file, that is information including:

• plugintype
• pluginname
• filepath
• brief summary of purpose
• example
• description

We can use this data to create a consistent look and feel which is reusable.

The default description of the file is provided in an mdx file. Additional descripton data can be added using the extraDescription property, or entirely replaced with the description property.

Likewise a default example can be provided, but this can be modified from a specific plugintype.

Equally the plugintypecan be specified in a specific component type (e.g. antivirus) and the title showing the path to the file will be updated using data from the standad Mooodle components.json. For example, the common files shows information for a generic version.php, but the activity module docs adds its own using:

<VersionPHP
    plugintype='mod'
    pluginname='[modname]'
/>

Likewise the Antivirus documentaiton wishes to specify a better example for its settings.php. This can be achieved with:

export const settingsExample = `
if ($ADMIN->fulltree) {
    $settings->add(
        new admin_setting_configexecutable(
            'antivirus_scanmyfile/pathtoscanner',",
            new lang_string('pathtoscanner', 'antivirus_scanmyfile'),",
            new lang_string('configpathtoscanner', 'antivirus_scanmyfile'),",
            ''",
        )
    );
}
`;

<SettingsPHP
    plugintype="antivirus"
    pluginname="scanmyfile"
    example={settingsExample}
/>

The standard description will beu sed, but the example filename will have the path lib/antivirus/scanmyfile/settings.php. The lib/antivirus comes from the standard Moodle components.json and the plugintype="antivirus". The scanmyfile comes from pluginname, and the settings.php is specifeid in the generic antivirus settings as the default filename to use. The custom example is specified as an exported constant and passed into example.

In addition to this, the docs pages are version-speciifc so we should ues the components.json for the correct version.

This means that we do a little bit of currying and provide a default version of the getter in the /docs/_utils.tsx file which includes the version-speific helper, and other useful information.

[sarjona]

Thanks a lot for working on this huge feature to simplify the creation of the plugin type pages! I think that's a great idea and, although the visualization can still be slightly improved, it's a very good improvement! Well done.

As you'll see, I've raised a few questions and sent some suggestions. Apart from that, I have one more comment, related to the way categories are displayed: as you can see in the following screenshot, content below each plugin type is not consistent (for instance, a couple of them are displaying the <Since xxx label):

[andrewnicols]

As you'll see, I've raised a few questions and sent some suggestions.

I think I've resolved all but one of these appropriately. The final one is awaiting feedback from you re the question bank plugin type.

Apart from that, I have one more comment, related to the way categories are displayed: as you can see in the following screenshot, content below each plugin type is not consistent (for instance, a couple of them are displaying the <Since xxx label):

This is a bug in Docusaurus. I've asked on their Discord chat if there's an existing issue for it - waiting to hear back.

I'll rebase my code now (some conflicts to resolve) and then I'll update the patch.

[sarjona]

Hi Andrew!
Thanks a lot for clarifying the raised points :-)
The patch looks good and I think it's ready to be merged. Besides, I've just seen the issue with the categories has been fixed too! <3