Obtain the latest API doc and event twig config

[wpjscc]

Hello, do you have the latest configurations for api-doc.twig and api-event.twig? It seems that the versions in the repository are rather outdated, and I encountered an error when running on PHP 8.0.9.

An exception has been thrown during the rendering of a template ("Array to string conversion") in "__string_template__c23d3d5bc470c6d71c9227ac9906ddeb7b71a7e762fdc56cbf32c0f5c5e77aa7" at line 10.

Additionally, could you provide a copy of the API configuration?

[
  'winterbranch12api' => [
      'name' => 'API Documentation',
      'type' => 'php',
      'source' => 'local',
      'path' => base_path(''),
      'sourcePaths' => [
      'modules/backend',
      'modules/cms',
      'modules/system',
  ],
],

When I commented out the line causing the error, there was a significant discrepancy compared to the official documentation.

Previously, I translated the documentation into Chinese using Google Translate (https://docs.wpjs.cc), but the meaning was considerably altered. Now, since utilizing GPT is quite cost-effective, translating with GPT would yield much better results.

To ensure consistency with the official website, I would appreciate your support with the aforementioned elements. Thank you.

[LukeTowers]

Here's the configuration we use for the main WinterCMS.com docs site:

<?php

namespace Winter\WinterDocs;

use Cms\Classes\Controller;
use Cms\Classes\Theme;
use Event;
use Request;
use System\Classes\PluginBase;
use Winter\Storm\Support\Str;

class Plugin extends PluginBase
{
    public function pluginDetails(): array
    {
        return [
            'name' => 'Winter Docs',
            'description' => 'A stub plugin to handle documentation on the Winter CMS site.',
            'author' => 'Winter CMS Maintainers',
            'icon' => 'icon-book'
        ];
    }

    public function boot()
    {
        $path = Request::path();
        if (Str::startsWith($path, 'docs')) {
            // Use the docs theme for all requests under /docs
            Event::listen('cms.theme.getActiveTheme', function () {
                return 'docs';
            });

            // Use the summit theme for 404 pages
            Event::listen('cms.page.beforeDisplay', function ($controller, $url, $page) {
                if (!$page) {
                    return (new Controller(Theme::load('summit')))->run('/404');
                }
            });
        }
    }

    public function registerDocumentation(): array
    {
        return [
            // Winter CMS v1.2
            'winterbranch12' => [
                'name' => 'General Documentation',
                'type' => 'md',
                'source' => 'remote',
                'url' => 'https://github.com/wintercms/docs/archive/refs/heads/1.2.zip',
                'zipFolder' => 'docs-1.2',
                'repository' => [
                    'url' => 'https://github.com/wintercms/docs/tree/1.2',
                    'editUrl' => 'https://github.com/wintercms/docs/edit/1.2/%s.md',
                ],
                'ignorePaths' => [
                    'LICENSE.md',
                    'README.md',
                    'config',
                    'markup',
                    'ui'
                ],
            ],
            'winterbranch12markup' => [
                'name' => 'Markup Manual',
                'type' => 'md',
                'source' => 'remote',
                'url' => 'https://github.com/wintercms/docs/archive/refs/heads/1.2.zip',
                'zipFolder' => 'docs-1.2/markup',
                'repository' => [
                    'url' => 'https://github.com/wintercms/docs/tree/1.2/markup',
                    'editUrl' => 'https://github.com/wintercms/docs/edit/1.2/markup/%s.md',
                ],
            ],
            'winterbranch12ui' => [
                'name' => 'User Interface Manual',
                'type' => 'md',
                'source' => 'remote',
                'url' => 'https://github.com/wintercms/docs/archive/refs/heads/1.2.zip',
                'zipFolder' => 'docs-1.2/ui',
                'repository' => [
                    'url' => 'https://github.com/wintercms/docs/tree/1.2/ui',
                    'editUrl' => 'https://github.com/wintercms/docs/edit/1.2/ui/%s.md',
                ],
            ],
            'winterbranch12api' => [
                'name' => 'API Documentation',
                'type' => 'php',
                'source' => 'local',
                'path' => base_path(),
                'template' => base_path('themes/nabu/views/api-doc.htm'),
                'eventTemplate' => base_path('themes/nabu/views/api-event.htm'),
                'repository' => [
                    'url' => 'https://github.com/wintercms/winter',
                    'viewUrl' => function ($path, $startLine, $endLine) {
                        if (str_starts_with($path, 'vendor/winter/storm')) {
                            return sprintf(
                                'https://github.com/wintercms/storm/blob/1.2/src/%s#L%d-L%d',
                                $path,
                                $startLine,
                                $endLine
                            );
                        }

                        return sprintf(
                            'https://github.com/wintercms/winter/blob/1.2/%s#L%d-L%d',
                            $path,
                            $startLine,
                            $endLine
                        );
                    },
                ],
                'sourcePaths' => [
                    'modules/system',
                    'modules/backend',
                    'modules/cms',
                    'vendor/winter/storm/src',
                ],
                'ignorePaths' => [
                    'modules/*/ServiceProvider.php',
                    'modules/*/{database,lang,views,vendor,layouts,tests}/**',
                    'modules/*/controllers/*/*',
                    'modules/*/**/partials/**',
                    'vendor/winter/storm/src/**/Migrations/**'
                ],
            ],
            // Winter CMS Develop Branch
            'winterdev' => [
                'name' => 'General Documentation',
                'type' => 'md',
                'source' => 'remote',
                'url' => 'https://github.com/wintercms/docs/archive/refs/heads/develop.zip',
                'zipFolder' => 'docs-develop',
                'repository' => [
                    'url' => 'https://github.com/wintercms/docs/tree/develop',
                    'editUrl' => 'https://github.com/wintercms/docs/edit/develop/%s.md',
                ],
                'ignorePaths' => [
                    'LICENSE.md',
                    'README.md',
                    'config',
                    'markup',
                    'ui'
                ],
            ],
            'winterdevmarkup' => [
                'name' => 'Markup Manual',
                'type' => 'md',
                'source' => 'remote',
                'url' => 'https://github.com/wintercms/docs/archive/refs/heads/develop.zip',
                'zipFolder' => 'docs-develop/markup',
                'repository' => [
                    'url' => 'https://github.com/wintercms/docs/tree/develop/markup',
                    'editUrl' => 'https://github.com/wintercms/docs/edit/develop/markup/%s.md',
                ],
            ],
            'winterdevui' => [
                'name' => 'User Interface Manual',
                'type' => 'md',
                'source' => 'remote',
                'url' => 'https://github.com/wintercms/docs/archive/refs/heads/develop.zip',
                'zipFolder' => 'docs-develop/ui',
                'repository' => [
                    'url' => 'https://github.com/wintercms/docs/tree/develop/ui',
                    'editUrl' => 'https://github.com/wintercms/docs/edit/develop/ui/%s.md',
                ],
            ],
            'winterdevapi' => [
                'name' => 'API Documentation',
                'type' => 'php',
                'source' => 'local',
                'path' => base_path(),
                'template' => base_path('themes/nabu/views/api-doc.htm'),
                'eventTemplate' => base_path('themes/nabu/views/api-event.htm'),
                'repository' => [
                    'url' => 'https://github.com/wintercms/winter',
                    'viewUrl' => function ($path, $startLine, $endLine) {
                        if (str_starts_with($path, 'vendor/winter/storm')) {
                            return sprintf(
                                'https://github.com/wintercms/storm/blob/develop/src/%s#L%d-L%d',
                                $path,
                                $startLine,
                                $endLine
                            );
                        }

                        return sprintf(
                            'https://github.com/wintercms/winter/blob/develop/%s#L%d-L%d',
                            $path,
                            $startLine,
                            $endLine
                        );
                    },
                ],
                'sourcePaths' => [
                    'modules/system',
                    'modules/backend',
                    'modules/cms',
                    'vendor/winter/storm/src',
                ],
                'ignorePaths' => [
                    'modules/*/ServiceProvider.php',
                    'modules/*/{database,lang,views,vendor,layouts,tests}/**',
                    'modules/*/controllers/*/*',
                    'modules/*/**/partials/**',
                    'vendor/winter/storm/src/**/Migrations/**'
                ],
            ]
        ];
    }
}

routes.php:

Route::get('sitemap_index.xml', function () {
    $sitemapElements = '';
    $sitemaps = [
        'sitemap.xml',
        'docs/sitemap.xml',
    ];
    foreach ($sitemaps as $sitemap) {
        $sitemapElements .= '<sitemap><loc>' . Request::root() . '/' . $sitemap . '</loc></sitemap>';
    }
    return Response::make(trim("
        <?xml version=\"1.0\" encoding=\"UTF-8\"?>
        <sitemapindex xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">
            $sitemapElements
        </sitemapindex>
        "))->header('Content-Type', 'application/xml');
});

Route::get('docs/sitemap.xml', function ()
{
    try {
        $definition = Definition::where('theme', 'docs')->firstOrFail();
    } catch (ModelNotFound $e) {
        return App::make(Controller::class)->setStatusCode(404)->run('/404');
    }

    return Response::make($definition->generateSitemap())
        ->header('Content-Type', 'application/xml');
});

/**
 * Kick off the CMS controller under the docs/ route
 */
Route::any('docs/{slug?}', 'Cms\Classes\CmsController@run')->where('slug', '(.*)?')->middleware('web');

Event::listen('cms.beforeRoute', function () {
    $path = Request::path();
    // Disable the CMS routes so that the docs/ route can take over for URL generation
    if (Str::startsWith($path, 'docs')) {
        return false;
    }
});

[LukeTowers]

Not sure exactly what you mean when you say api-event.twig and api-doc.twig.

[wpjscc]

Wow, thank you! The api-doc.twig now allows customization of base_path('themes/nabu/views/api-doc.htm'), yet it does not function in https://github.com/wintercms/wn-docs-plugin/blob/main/views/api-doc.twig

[LukeTowers]

@wpjscc I'm not sure I understand what you're trying to say, can you try explaining it in a different way?

[bennothommo]

@LukeTowers I believe what @wpjscc is saying is that there is a default api-doc.twig and api-event.twig template in the Docs plugin which is used if the docs config in the plugin does not specify a custom one (like we do). These templates are wildly out of date.

They would be correct, in this case, as I've been mainly working on the one in the Nabu theme. My intention was to de-Tailwindify and standardise the two templates for use elsewhere, but I haven't done so yet.

@wpjscc feel free to copy the two templates below from the Nabu theme and use them in your theme if you wish

• https://github.com/wintercms/wn-nabu-theme/blob/main/views/api-doc.htm
• https://github.com/wintercms/wn-nabu-theme/blob/main/views/api-event.htm