donatj/mddoc

Powerful, User Directed Markdown Generator

v0.3.0 2022-01-07 18:35 UTC

This package is auto-updated.

Last update: 2022-11-01 16:03:44 UTC


README

Latest Stable Version Total Downloads License CI

A simple, directed markdown documentation generator.

Relatively early in development and very open to issues feature requests.

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/flags: ~1.4
  • donatj/cli-toolkit: ~0.2
  • donatj/mddom: ~0.1.0
  • phpdocumentor/reflection: ~5.1
  • symfony/polyfill-php80: ^1.23

Example

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

<mddoc>

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

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

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

Relatively early in development and very open to issues feature requests.

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

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

Usages

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

Full API Docs (WIP)

See: DOCS.md