TLDR

To get started building some docs

1. git clone [email protected]:dustinb/docsify-twig.git

2. Modify phpdoc.xml (elemens below) with your target and direcstory (source)

<transformer>
    <target>../docs/api</target>
  </transformer>
  <files>
    <directory>../res</directory>
  </files>

3. run sh api-build.sh. Will run composer, move template to correct location and build docs

docsify-twig

docsify-twig is a phpDocumentor template that outputs markdown. You don't have to use it in Docsify but the combination free form markdown served by Docsify + auto generated api reference is a great solution for project documentation.

I've looked at various ways to accomplish this using Dokuwiki or ApiGen and phpDocumentor + Docsify is the winner.

I found inspiration with phpdoc-md and I did get it to work but I needed access to some informaiton that wasn't being sent to the twig templates.

docsify-twig is a "real" phpDocumentor template based on responsive-twig along with a shell script. The shell script is needed because I couldn't figure out some things.

1. phpdocumentor templates seem to work best in vendor/phpdocumentor/phpdocumentor/data/templates/. Getting template file not found otherwise
2. Wasn't able to get twig Writer to save as .md extension
3. Twig caches a lot so shell script cleans things up for you

template.xml

I've left all the original responsive-twig html templates in. These can be used for reference on how to get information from phpdocumentor about your classes, methods, properties, interfaces etc.. I'm was only interested in classes so that is the only transformation I used.

    <transformationX query="indexes.namespaces" writer="twig" source="templates/responsive-twig/namespace.html.twig" />
    <transformationX query="indexes.packages" writer="twig" source="templates/responsive-twig/package.html.twig" />
    <transformation  query="indexes.classes" writer="twig" source="templates/docsify-twig/class.md.twig" />

If you need namespaces or other transformations remove the X and change html to md. Create a new file for the .md version (or copy the html to start with) and modify it to output markdown instead of HTML.