Pages feature

[jaapio]

Every project needs besides it's documenation some extra pages, like overviews of versions, related projects and other informal pages that are not related to a documentation set. To accomplish this it would make sense to introduce a basic site builder.

Why do this in phpDocumentor, we already have static site builders?

One could argue that phpDocumentor should not do the work of a static site builder, but in fact this is what we already do... we have all tools to be a static site generator. We can transform text formats to html, and include some dynamic behavior to by reading your code. So adding some extra configuration to make it possible to create project wide pages that are not attached to a version is just a small step.

Should phpDocumentor not be a plugin on static site builders?

I think it will be hard to make phpDocumentor connect with other site builders. It has a complex architecture and is not as easy as it might look to connect phpDocumentor with an existing application. The internal models are very rich... We would literally need to expose all the internals to allow static site builder to use the information we have.

Suggestion is to add a new configuration section based on the configuration we already have for guides. Like this:

<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor
        configVersion="3"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="https://www.phpdoc.org"
        xsi:noNamespaceSchemaLocation="data/xsd/phpdoc.xsd"
>
    <title>phpDocumentor</title>
    <paths>
        <output>build/website/docs</output>
    </paths>
    <pages>
        <source dsn=".">
            <path>README.md</path>
        </source>
    </pages>
    <version number="3.0.0">

The new pages section will output directly to th the output directory in paths. The versions folders are placed directly under the output directory. This allows our users to create a folder structure like this:

output

• index.html
• /css
• /js
• /3.0.0
  • /api
  • /guides

The guides folder is optional, and might also be placed in at the root level of the version. So a version can have a structure of docs that include the api docs.