README

A simple, directed markdown documentation generator for PHP projects.

A simple use-case is to generate a README.md based on the project's source code as well as other options as defined in the config file.

This projects allows you to define a set of directives for how to document a project, and output to markdown.

This allows everything from README's to entire websites to be generated using this tool.

This is done using a simple, expressive XML syntax. This includes:

• Automatic documentation of code
• Automatic composer requirements / installation instructions
• Raw and code-tag wrapped file inclusion
• Script output
• Automatic Badge Creation
• Creating sub-documents
• Much more

Requirements

• php: >=7.2
• ext-dom: *
• ext-json: *
• ext-libxml: *
• donatj/cli-toolkit: ^0.3.1
• donatj/flags: ^1.5
• donatj/mddom: ^0.2.0
• phpdocumentor/reflection: ~5.2.0
• psr/log: ^1|^2|^3
• symfony/polyfill-php80: ^1.28

Examples

• PhpUserAgent's README
• boomerang.work - The documentation site for Boomerang*!* is fully generated using this tool.

This very README you are reading (also including DOCS.md) is generated by the file .mddoc.xml.dist

<mddoc>
  <autoloader type="psr4" root="src" namespace="donatj\MDDoc"/>
  <docpage target="README.md">

    <section title="MDDoc">
      <badge-poser type="version"/>
      <badge-poser type="downloads"/>
      <badge-poser type="license"/>
      <badge-github-action name="donatj/mddoc" workflow-file="ci.yml"/>

      <text><![CDATA[
A simple, directed markdown documentation generator for PHP projects.

A simple use-case is to generate a README.md based on the project's source code as well as other options as defined in the config file.

This projects allows you to define a set of directives for *how* to document a project, and output to markdown.

This allows everything from README's to entire websites to be generated using this tool.

This is done using a simple, expressive XML syntax. This includes:

- Automatic documentation of code
- Automatic composer requirements / installation instructions
- Raw and code-tag wrapped file inclusion
- Script output
- Automatic Badge Creation
- Creating sub-documents
- Much more

]]></text>
      <section title="Requirements">
        <composer-requires/>
      </section>

      <section title="Examples">
        <text><![CDATA[
- PhpUserAgent's [README](https://github.com/donatj/PhpUserAgent)
- [boomerang.work](https://boomerang.work/) - The documentation site for Boomerang*!* is fully generated using this tool.

This very README you are reading (also including [DOCS.md](DOCS.md)) is generated by the file [.mddoc.xml.dist](.mddoc.xml.dist)
]]></text>
        <replace search="&#x9;" replace="  ">
          <source name=".mddoc.xml.dist" lang="xml"/>
        </replace>
      </section>

      <section title="Full API Docs (WIP)">
        <docpage target="DOCS.md">
          <section title="Full API Docs (WIP)">
            <recursive-directory warn-undocumented="false" name="src"/>
          </section>
        </docpage>
      </section>

      <section title="Configuration Syntax">
        <exec cmd="./bin/document-tags.php"/>
      </section>
    </section>
  </docpage>
</mddoc>

Full API Docs (WIP)

See: DOCS.md

Configuration Syntax

<autoloader />

Specifies an PHP autoloader to use for the documentation generation

This autoloader is used at the current documentation level and inherited by
all children

Multiple autoloaders can be specified, and they will be checked in the order
they are specified

These are necessary to specify by hand because the composer autoloaders
do not provide a method to locate a class by name without loading it,
which is necessary for documentation generation without code execution.

Attributes:

• type (required) - The type of autoloader to use, either "psr0" or "psr4"
• root (required) - The root directory of the autoloader
• namespace - The namespace of the autoloader, only used for psr4

<section>…</section>

Define a logical section of the generated documentation

Nesting sections results in the header level being increased (h1, h2, h3, etc)

Example:

<section title="This is an H1">  
   <section title="This is an H2">  
        <section title="This is an H3">  
          <text>Some Text</text>  
        </section>  
   </section>  
</section>  

Results in:

# This is an H1  
  
## This is an H2  
  
### This is an H3  
  
Some Text  

Attributes:

• title (required) - The heading of the section

<replace>…</replace>

Replace text in the wrapped content. Optionally use a preg_replace() regex.

Attributes:

• search (required) - The text to search for
• replace (required) - The text to replace with
• regex - Whether to use a regex or not - expects "true" or "false" - defaults to "false"

<docpage>…</docpage>

Documentation page - stores the contents of child elements to a file

Nesting docpages results in a link being added in the parent page to the child page

Inherits all attributes from <file>

Attributes:

• target (required) - Filename to output
• link - Optional custom link for parent documents
• link-text - Optional custom text for the link in parent documents
• link-pre-text - Optional custom text to precede the link in parent documents
• link-post-text - Optional custom text to follow the link in parent documents

<text />

Include either raw or cdata text content

Example:

<text>Some Text</text>  
<text><![CDATA[Some Text]]></text>  

<file />

Generate documentation for a single PHP file

Attributes:

• name (required) - The file to document
• skip-class-header [recursive] - Skip the class header line
• skip-class-constants [recursive] - Skip the class constants section
• method-filter - Regex to filter methods by - specify methods to be matched
• skip-method-returns - Skip the method return section
• warn-undocumented [recursive] - Generate warning for undocumented methods. Defaults to "true".

<recursive-directory>…</recursive-directory>

Recursively search a directory for php files to generate documentation for

Attributes:

• name (required) - The directory to recursively search for files to document
• file-filter - A regex to filter files by - specify files to be matched

<include />

Include the contents of a file

Attributes:

• name (required) - The poth of the file to include

<source />

Include a source code block either as a file or inline

Example:

<source name="path/to/file.php" lang="php" />  
<source lang="js">  
console.log('Hello World');  
</source>  

Attributes:

• name - filename of optional source file
• lang - Optional language name for the opening

<composer-install />

Reads the current projects' composer.json file and outputs the install command

Attributes:

• text - Text to display before the install command
• global - Whether to include global subcommand
• dev - Whether to include --dev flag
• package-names - Package name override. Comma delimited. Defaults to name key of composer.json

<composer-requires />

Reads the current projects' composer.json file and outputs the required packages, versions and extensions

<badge />

Include a badge "shield" image from a given url

Attributes:

• src - The image url (required)
• alt - The image alt text (required)
• href - The optional url to link to wrap the badge in
• title - The optional link title

<badge-coveralls />

Include a coverage badge from BadgeCoveralls.io

Attributes:

• name - The BadgeCoveralls name of the Project. Required.

This includes the service name, e.g. "github/donatj/php-dnf-solver"

• branch - The branch to show. Defaults to empty which shows the default branch

<badge-poser />

Include a badge "shield" image from Pugx Poser https://poser.pugx.org/

Attributes:

• type (required) - The type of badge to display. One of: "version" "downloads" "unstable" "license" "monthly" "daily" "phpversion"
  "composerlock"
• name - The packagist name of the package. Defaults to the name key of the composer.json file in the root of the project. Required if the composer.json file is not present.
• suffix - The poser endpoint to use. Defaults based on the type

<badge-travis />

Include a badge "shield" image from Travis CI

Attributes:

• name (required) - The packagist name of the Travis Project. Defaults to the name key of the composer.json file in the root of the
  project. Required if the composer.json file is not present.
• branch - The branch to show. Defaults to "master"

<badge-scrutinizer />

Include a badge "shield" image from Scrutinizer CI

Attributes:

• name (required) - The packagist name of the Scrutinizer Project. Defaults to the name key of the composer.json file in the root of
  the project. Required if the composer.json file is not present.
• type (required) - The type of badge to display. One of: "quality" "coverage" "build-status"
• suffix - The Scrutinizer endpoint to use. Defaults based on the type
• branch - The branch to show. Defaults to "master"

<badge-shielded />

Include a badge "shield" image from Shielded.dev

Either the id or the color, title, and text options must be provided.

Attributes:

• id - The ID of the badge to display when displaying a dynamic badge.
• color - The color of the badge when displaying a static badge.
• title - The title of the badge when displaying a static badge.
• text - The text of the badge when displaying a static badge.

<badge-github-action />

Include a badge "shield" image for a GitHub Actions workflow

Attributes:

• name (required) - The name of the .yml file in the .github/workflows/ directory including the .yml extension
• branch - The name of the branch to show the badge for. Defaults to the default branch.
• event
• workflow-file (required) - The filename of the workflow file to use as the badge source

<exec />

Execute a command and include the standard output in the documentation

Attributes:

• cmd (required) - The command to execute
• format - The format to output the result in - options include "raw" "code" and "code-block" defaults to "raw"
• allow-error - Set to 'true' to allow non-zero exit codes to continue