Rework of build process

[froschdesign]

@weierophinney

Problem

At the moment we have two different entry pages for the documentation. One of them is outdated.

Suggestion

With version 1.0 of MkDocs we can add external links to the navigation. This allows us to move the documentation entry page from framework.zend.com to docs.zendframework.com.

• switch to version 1.0 of MkDocs
• add links to ZF1, ZF2 and ZF3 to the sub-navigation
• use MkDocs to create the packages list
• update the script for preparing the component list
• use the same build process like in all other packages (branch gh-pages)
• remove the documentation entry page (with the outdated packages list) from framework.zend.com

Preview

Extended mkdocs.yml

docs_dir: docs/book
site_dir: docs/html
nav:
  - Home: index.md
  - 'Zend Framework 3':
    - 'Getting Started': https://docs.zendframework.com/tutorials/getting-started/overview/
    - Tutorials: https://docs.zendframework.com/tutorials/
  - 'Zend Framework 2':
    - 'Getting Started': https://framework.zend.com/manual/2.4/en/user-guide/overview.html
    - 'Reference Guide': https://framework.zend.com/manual/2.4/en/index.html
    - API: https://framework.zend.com/docs/api/zf2
  - 'Zend Framework 1':
    - 'Getting Started': https://framework.zend.com/manual/1.12/en/learning.quickstart.html
    - 'Reference Guide': https://framework.zend.com/manual/1.12/en/manual.html
    - API: https://framework.zend.com/docs/api/zf1
site_name: Documentation
site_description: 'Documentation for the MVC Framework, Expressive, and all Components'
repo_url: 'https://github.com/zendframework/zendframework.github.io'
copyright: 'Copyright (c) 2015-2018 <a href="https://www.zend.com/">Zend Technologies USA Inc.</a>'
theme:
  name: null
  custom_dir: theme/
markdown_extensions:
- markdown.extensions.codehilite:
    use_pygments: False
edit_uri: edit/master/${DOCS_DIR}/
extra:
  show_special_homepage: true
  component_list:
    - { group_name: 'Learn ZF', packages: [{ name: Tutorials, package: zendframework/tutorials, url: 'https://docs.zendframework.com/tutorials', description: 'Learn how to create zend-mvc applications, get in-depth guides into components, and discover how to migrate your applications to version 3!' }] }
    - { group_name: 'MVC Framework', packages: [{ name: 'Module Manager', package: zendframework/zend-modulemanager, url: 'https://docs.zendframework.com/zend-modulemanager/', description: 'Modular application system for zend-mvc applications.' }, { name: MVC, package: zendframework/zend-mvc, url: 'https://docs.zendframework.com/zend-mvc/', description: 'Zend Framework''s event-driven MVC layer, including MVC Applications, Controllers, and Plugins.' }, { name: 'MVC-Console integration', package: zendframework/zend-mvc-console, url: 'https://docs.zendframework.com/zend-mvc-console/', description: 'Integration between zend-mvc and zend-console.' }, { name: 'MVC-i18n integration', package: zendframework/zend-mvc-i18n, url: 'https://docs.zendframework.com/zend-mvc-i18n/', description: 'Integration between zend-mvc and zend-i18n.' }, { name: 'fileprg() plugin', package: zendframework/zend-mvc-plugin-fileprg, url: 'https://docs.zendframework.com/zend-mvc-plugin-fileprg/', description: 'Post/Redirect/Get plugin with file upload handling for zend-mvc controllers.' }, { name: 'flashmessenger() plugin', package: zendframework/zend-mvc-plugin-flashmessenger, url: 'https://docs.zendframework.com/zend-mvc-plugin-flashmessenger/', description: 'Plugin for creating and exposing flash messages via zend-mvc controllers.' }, { name: 'identity() plugin', package: zendframework/zend-mvc-plugin-identity, url: 'https://docs.zendframework.com/zend-mvc-plugin-identity/', description: 'Plugin for retrieving the current authenticated identity within zend-mvc controllers.' }, { name: 'prg() plugin', package: zendframework/zend-mvc-plugin-prg, url: 'https://docs.zendframework.com/zend-mvc-plugin-prg/', description: 'Post/Redirect/Get plugin for zend-mvc controllers.' }, { name: 'PSR-7 Bridge', package: zendframework/zend-psr7bridge, url: 'https://docs.zendframework.com/zend-psr7bridge/', description: 'PSR-7 &lt;-&gt; zend-http message conversions.' }, { name: Test, package: zendframework/zend-test, url: 'https://docs.zendframework.com/zend-test/', description: 'Tools to facilitate unit testing of zend-mvc applications.' }] }
    - { group_name: 'Expressive and PSR-15 Middleware', packages: [{ name: Expressive, package: zendframework/zend-expressive, url: 'https://docs.zendframework.com/zend-expressive/', description: 'PSR-7 middleware in minutes.' }, { name: 'Authentication for Expressive and PSR-7', package: zendframework/zend-expressive-authentication, url: 'https://docs.zendframework.com/zend-expressive-authentication/', description: 'Authentication middleware for Expressive and PSR-7 applications.' }, { name: 'HTTP Basic Authentication for Expressive and PSR-7', package: zendframework/zend-expressive-authentication-basic, url: 'https://docs.zendframework.com/zend-expressive-authentication-basic/', description: 'HTTP Basic Authentication adapter for zend-expressive-authentication.' }, { name: 'Username/password authentication for zend-expressive-authentication', package: zendframework/zend-expressive-authentication-session, url: 'https://docs.zendframework.com/zend-expressive-authentication-session/', description: 'Username/password, session-backed authentication adapter for zend-expressive-authentication.' }, { name: 'zend-authentication integration for Expressive', package: zendframework/zend-expressive-authentication-zendauthentication, url: 'https://docs.zendframework.com/zend-expressive-authentication-zendauthentication/', description: 'zend-authentication adapter for zend-expressive-authentication.' }, { name: Flash, package: zendframework/zend-expressive-flash, url: 'https://docs.zendframework.com/zend-expressive-flash/', description: 'Flash messages for PSR-7 and Expressive applications.' }, { name: 'HAL for PSR-7', package: zendframework/zend-expressive-hal, url: 'https://docs.zendframework.com/zend-expressive-hal/', description: 'Hypertext Application Language (HAL) for PSR-7.' }, { name: 'HTTP Request Handler Runner', package: zendframework/zend-httphandlerrunner, url: 'https://docs.zendframework.com/zend-httphandlerrunner/', description: 'Execute PSR-15 RequestHandlerInterface instances and emit responses they generate.' }, { name: 'Problem Details', package: zendframework/zend-problem-details, url: 'https://docs.zendframework.com/zend-problem-details/', description: 'PSR-7 Problem Details for HTTP API responses and middleware.' }, { name: 'PSR-7 Sessions', package: zendframework/zend-expressive-session, url: 'https://docs.zendframework.com/zend-expressive-session/', description: 'Session container and middleware PSR-7 and Expressive applications.' }, { name: 'PSR-7 Sessions via ext-session', package: zendframework/zend-expressive-session-ext, url: 'https://docs.zendframework.com/zend-expressive-session-ext/', description: 'PHP ext-session persistence for PSR-7 sessions.' }, { name: Stratigility, package: zendframework/zend-stratigility, url: 'https://docs.zendframework.com/zend-stratigility/', description: 'PSR-7 middleware foundation for building and dispatching middleware pipelines.' }] }
    - { group_name: 'Tooling and Composer Plugins', packages: [{ name: 'Component Installer', package: zendframework/zend-component-installer, url: 'https://docs.zendframework.com/zend-component-installer/', description: 'Composer plugin for injecting modules and configuration providers into application configuration.' }] }
    - { group_name: Components, packages: [{ name: Authentication, package: zendframework/zend-authentication, url: 'https://docs.zendframework.com/zend-authentication', description: 'Authenticate users via a variety of adapters, and provide the authenticated identity to your application.' }, { name: Barcode, package: zendframework/zend-barcode, url: 'https://docs.zendframework.com/zend-barcode', description: 'Programmatically create and render barcodes as images or in PDFs.' }, { name: Cache, package: zendframework/zend-cache, url: 'https://docs.zendframework.com/zend-cache/', description: 'Caching implementation with a variety of storage options, as well as codified caching strategies for callbacks, classes, and output.' }, { name: Captcha, package: zendframework/zend-captcha, url: 'https://docs.zendframework.com/zend-captcha/', description: 'Generate and validate CAPTCHAs using Figlets, images, ReCaptcha, and more.' }, { name: Code, package: zendframework/zend-code, url: 'https://docs.zendframework.com/zend-code/', description: 'Extensions to the PHP Reflection API, static code scanning, and code generation.' }, { name: Config, package: zendframework/zend-config, url: 'https://docs.zendframework.com/zend-config/', description: 'Read and write configuration files.' }, { name: ConfigAggregator, package: zendframework/zend-config-aggregator, url: 'https://docs.zendframework.com/zend-config-aggregator/', description: 'Lightweight library for collecting and merging configuration from different sources.' }, { name: 'ConfigAggregator ModuleManager Plugin', package: zendframework/zend-config-aggregator-modulemanager, url: 'https://docs.zendframework.com/zend-config-aggregator-modulemanager/', description: 'Consume zend-mvc modules as configuration providers within zend-config-aggregator.' }, { name: 'ConfigAggregator Templated Parameters PostProcessor', package: zendframework/zend-config-aggregator-parameters, url: 'https://docs.zendframework.com/zend-config-aggregator-parameters/', description: 'PostProcessor extension for zendframework/zend-config-aggregator to allow usage of templated parameters within your configuration.' }, { name: Console, package: zendframework/zend-console, url: 'https://docs.zendframework.com/zend-console/', description: 'Build console applications using getopt syntax or routing, complete with prompts' }, { name: Crypt, package: zendframework/zend-crypt, url: 'https://docs.zendframework.com/zend-crypt/', description: 'Strong cryptography tools and password hashing.' }, { name: CSRF, package: zendframework/zend-expressive-csrf, url: 'https://docs.zendframework.com/zend-expressive-csrf/', description: 'CSRF token generation and validation for PSR-7 and Expressive applications.' }, { name: DB, package: zendframework/zend-db, url: 'https://docs.zendframework.com/zend-db/', description: 'Database abstraction layer, SQL abstraction, result set abstraction, and RowDataGateway and TableDataGateway implementations.' }, { name: Debug, package: zendframework/zend-debug, url: 'https://docs.zendframework.com/zend-debug/', description: 'Safely dump debug information to HTML.' }, { name: DI, package: zendframework/zend-di, url: 'https://docs.zendframework.com/zend-di/', description: 'Automated dependency injection and instance manager.' }, { name: Diactoros, package: zendframework/zend-diactoros, url: 'https://docs.zendframework.com/zend-diactoros/', description: 'PSR-7 HTTP message implementations.' }, { name: DOM, package: zendframework/zend-dom, url: 'https://docs.zendframework.com/zend-dom/', description: 'Query HTML and XML documents using XPath or CSS selectors.' }, { name: Escaper, package: zendframework/zend-escaper, url: 'https://docs.zendframework.com/zend-escaper/', description: 'Securely and safely escape HTML, HTML attributes, JavaScript, CSS, and URLs.' }, { name: EventManager, package: zendframework/zend-eventmanager, url: 'https://docs.zendframework.com/zend-eventmanager/', description: 'Implement events, signal slots, aspects, and observers!' }, { name: Feed, package: zendframework/zend-feed, url: 'https://docs.zendframework.com/zend-feed/', description: 'Consume and generate Atom and RSS feeds, and interact with Pubsubhubbub.' }, { name: File, package: zendframework/zend-file, url: 'https://docs.zendframework.com/zend-file/', description: 'Locate PHP classfiles.' }, { name: Filter, package: zendframework/zend-filter, url: 'https://docs.zendframework.com/zend-filter/', description: 'Programmatically filter and normalize data and files.' }, { name: Form, package: zendframework/zend-form, url: 'https://docs.zendframework.com/zend-form/', description: 'Validate and display simple and complex forms, casting forms to business objects and vice versa.' }, { name: HTTP, package: zendframework/zend-http, url: 'https://docs.zendframework.com/zend-http/', description: 'HTTP message and header abstractions, and HTTP client implementation.  (Not a PSR-7 implementation.)' }, { name: Hydrator, package: zendframework/zend-hydrator, url: 'https://docs.zendframework.com/zend-hydrator/', description: 'Serialize objects to arrays, and vice versa.' }, { name: InputFilter, package: zendframework/zend-inputfilter, url: 'https://docs.zendframework.com/zend-inputfilter/', description: 'Normalize and validate input sets from the web, APIs, the CLI, and more, including files.' }, { name: Internationalization, package: zendframework/zend-i18n, url: 'https://docs.zendframework.com/zend-i18n/', description: 'Provide translations for your application, and filter and validate internationalized values.' }, { name: JSON, package: zendframework/zend-json, url: 'https://docs.zendframework.com/zend-json/', description: 'De/Serialize JSON in PHP, including JavaScript expressions.' }, { name: 'JSON-RPC Server', package: zendframework/zend-json-server, url: 'https://docs.zendframework.com/zend-json-server/', description: 'JSON-RPC implementation for PHP.' }, { name: LDAP, package: zendframework/zend-ldap, url: 'https://docs.zendframework.com/zend-ldap/', description: 'Perform LDAP operations, including binding, searching and modifying entries in an LDAP directory.' }, { name: Loader, package: zendframework/zend-loader, url: 'https://docs.zendframework.com/zend-loader/', description: 'Autoloading and plugin loading strategies.' }, { name: Log, package: zendframework/zend-log, url: 'https://docs.zendframework.com/zend-log/', description: 'Robust, composite logger with filtering, formatting, and PSR-3 support.' }, { name: Mail, package: zendframework/zend-mail, url: 'https://docs.zendframework.com/zend-mail/', description: 'Parse, create, store, and send email messages, using a variety of storage and transport protocols.' }, { name: Math, package: zendframework/zend-math, url: 'https://docs.zendframework.com/zend-math/', description: 'Create cryptographically secure pseudo-random numbers, and manage big integers.' }, { name: Memory, package: zendframework/zend-memory, url: 'https://docs.zendframework.com/zend-memory/', description: 'Manage data in an environment with limited memory.' }, { name: MIME, package: zendframework/zend-mime, url: 'https://docs.zendframework.com/zend-mime/', description: 'Create and parse MIME messages and parts.' }, { name: Navigation, package: zendframework/zend-navigation, url: 'https://docs.zendframework.com/zend-navigation/', description: 'Manage trees of pointers to web pages in order to build navigation systems.' }, { name: Paginator, package: zendframework/zend-paginator, url: 'https://docs.zendframework.com/zend-paginator/', description: 'Paginate collections of data from arbitrary sources.' }, { name: ACL, package: zendframework/zend-permissions-acl, url: 'https://docs.zendframework.com/zend-permissions-acl/', description: 'Create, manage, and query access control lists.' }, { name: RBAC, package: zendframework/zend-permissions-rbac, url: 'https://docs.zendframework.com/zend-permissions-rbac/', description: 'Provide and query Role-Based Access Controls for your application.' }, { name: ProgressBar, package: zendframework/zend-progressbar, url: 'https://docs.zendframework.com/zend-progressbar/', description: 'Create and update progress bars in different environments.' }, { name: Router, package: zendframework/zend-router, url: 'https://docs.zendframework.com/zend-router/', description: 'Flexible routing system for HTTP and console applications.' }, { name: Serializer, package: zendframework/zend-serializer, url: 'https://docs.zendframework.com/zend-serializer/', description: 'Serialize and deserialize PHP structures to a variety of representations.' }, { name: Server, package: zendframework/zend-server, url: 'https://docs.zendframework.com/zend-server/', description: 'Create Reflection-based RPC servers.' }, { name: ServiceManager, package: zendframework/zend-servicemanager, url: 'https://docs.zendframework.com/zend-servicemanager/', description: 'Factory-Driven Dependency Injection Container' }, { name: 'ServiceManager-Di integration', package: zendframework/zend-servicemanager-di, url: 'https://docs.zendframework.com/zend-servicemanager-di/', description: 'zend-di integration for zend-servicemanager' }, { name: Session, package: zendframework/zend-session, url: 'https://docs.zendframework.com/zend-session/', description: 'Object-oriented interface to PHP sessions and storage.' }, { name: SOAP, package: zendframework/zend-soap, url: 'https://docs.zendframework.com/zend-soap/', description: 'Create, serve, and access SOAP applications, and parse and generate WSDL.' }, { name: Stdlib, package: zendframework/zend-stdlib, url: 'https://docs.zendframework.com/zend-stdlib/', description: 'SPL extensions, array utilities, error handlers, and more.' }, { name: Tag, package: zendframework/zend-tag, url: 'https://docs.zendframework.com/zend-tag/', description: 'Manipulate and weight taggable items, and create tag clouds.' }, { name: Text, package: zendframework/zend-text, url: 'https://docs.zendframework.com/zend-text/', description: 'Create FIGlets and text-based tables.' }, { name: URI, package: zendframework/zend-uri, url: 'https://docs.zendframework.com/zend-uri/', description: 'Object oriented interface to URIs, with facilities for validation.' }, { name: Validator, package: zendframework/zend-validator, url: 'https://docs.zendframework.com/zend-validator/', description: 'Validation classes for a wide range of domains, and the ability to chain validators to create complex validation criteria.' }, { name: View, package: zendframework/zend-view, url: 'https://docs.zendframework.com/zend-view/', description: 'Flexible view layer supporting and providing multiple view layers, helpers, and more.' }, { name: XML-RPC, package: zendframework/zend-xmlrpc, url: 'https://docs.zendframework.com/zend-xmlrpc/', description: 'Fully-featured XML-RPC server and client implementations.' }, { name: XML2JSON, package: zendframework/zend-xml2json, url: 'https://docs.zendframework.com/zend-xml2json/', description: 'Convert XML documents to JSON.' }, { name: ZendDiagnostics, package: zendframework/zenddiagnostics, url: 'https://docs.zendframework.com/zend-diagnostics/', description: 'Universal set of diagnostic tests for PHP applications.' }] }

[froschdesign]

I created a PR on the theme repository to include the packages list: https://github.com/zendframework/zf-mkdoc-theme/pull/57

[froschdesign]

Related to https://github.com/zendframework/zf-mkdoc-theme/issues/52

[weierophinney]

:+1: I really like this. Have you started work on it yet?

I'll be going through the zf-mkdock-theme PRs today, and we can then hopefully start building out all components as well; getting this in place would be a great last step in that process.

[froschdesign]

@weierophinney

Have you started work on it yet?

I have deleted all HTML, CSS und JS files and updated the prepare_component_list.php:

require_once __DIR__ . '/vendor/autoload.php';

$root      = realpath(getcwd());
$listFile  = sprintf('%s/zf-component-list.json', $root);

if (! is_readable($listFile)) {
    fwrite(STDERR, "Unable to locate zf-component-list.json in root directory; did you run 'make'?\n");
    exit(1);
}

$json = file_get_contents($listFile);
$packages = json_decode($json, true);

// Group packages by type
$packagesByType = [
    'learn'      => [
        'group_name' => 'Learn ZF',
        'packages'   => [],
    ],
    'mvc'        => [
        'group_name' => 'MVC Framework',
        'packages'   => [],
    ],
    'middleware' => [
        'group_name' => 'Expressive and PSR-15 Middleware',
        'packages'   => [],
    ],
    'projects'   => [
        'group_name' => 'Tooling and Composer Plugins',
        'packages'   => [],
    ],
    'components' => [
        'group_name' => 'Components',
        'packages'   => [],
    ],
];

$types = array_keys($packagesByType);

// Sort packages into various groups
$packagesByType = array_reduce(
    $packages,
    function ($grouped, $package) use ($types) {
        if (! isset($package['group']) || ! in_array($package['group'], $types, true)) {
            $package['group'] = 'components';
        }

        $grouped[$package['group']]['packages'][] = [
            'name'        => $package['name'],
            'package'     => $package['package'],
            'url'         => $package['url'],
            'description' => $package['description'],
        ];

        return $grouped;
    },
    $packagesByType
);

// Create YAML
$yaml = "\n  " . Symfony\Component\Yaml\Yaml::dump(
        [
            'component_list' => array_values($packagesByType),
        ]
    );

// Add list to mkdocs.yml
file_put_contents(__DIR__ . '/mkdocs.yml', $yaml, FILE_APPEND);

echo 'Added component list to mkdocs.yml';

The script requires symfony/yaml.

And the new index.md:

# Zend Framework<br>Documentation

Documentation for the MVC Framework, Expressive, and all Components

[froschdesign]

Another idea for the packages overview: we have already a table of contents on every page. We should add this also for the package list:

I will create a pull request for this.