donatj / mddoc
Powerful, User Directed Markdown Documentation Generator
Fund package maintenance!
www.paypal.me/donatj/15
Ko Fi
donatj
Installs: 28 667
Dependents: 4
Suggesters: 0
Security: 0
Stars: 1
Watchers: 3
Forks: 1
Open Issues: 4
Requires
- 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
- symfony/polyfill-php80: ^1.28
Requires (Dev)
- corpus/coding-standard: ^0.6.0
- donatj/drop: ~1.0
- friendsofphp/php-cs-fixer: ^3.3
- php-parallel-lint/php-parallel-lint: ^1.3
- squizlabs/php_codesniffer: ^3.7
- dev-master
- v0.10.1
- v0.10.0
- v0.9.1
- v0.9.0
- v0.8.1
- v0.8.0
- v0.7.0
- v0.6.0
- v0.5.0
- v0.4.0
- v0.3.0
- v0.2.0
- v0.1.1
- v0.1.0
- dev-dependabot/composer/phpdocumentor/reflection-approx-6.1.0
- dev-dependabot/composer/phpstan/phpstan-tw-2.0
- dev-dependabot/composer/corpus/coding-standard-tw-0.8.0
- dev-dependabot/composer/phpdocumentor/reflection-approx-6.0.0
- dev-ComposerOptions
- dev-ReplaceAutoloader
- dev-donatj-patch-1
- dev-feature/TagDocumentation
- dev-develop
- dev-dev-DOM
This package is auto-updated.
Last update: 2024-11-25 09:51:35 UTC
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="	" 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)
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 autoloadernamespace
- 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 forreplace
(required) - The text to replace withregex
- 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 outputlink
- Optional custom link for parent documentslink-text
- Optional custom text for the link in parent documentslink-pre-text
- Optional custom text to precede the link in parent documentslink-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 documentskip-class-header
[recursive] - Skip the class header lineskip-class-constants
[recursive] - Skip the class constants sectionmethod-filter
- Regex to filter methods by - specify methods to be matchedskip-method-returns
- Skip the method return sectionwarn-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 documentfile-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 filelang
- 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 commandglobal
- Whether to include global subcommanddev
- Whether to include --dev flagpackage-names
- Package name override. Comma delimited. Defaults toname
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 intitle
- 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 typebranch
- 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
extensionbranch
- 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 executeformat
- 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