evert / phpdoc-md

PHPDocumentor Markdown generator

PHPDocumentor MarkDown export

This is a script that can generate markdown (.md) files for your API documentation.

It is tailored for projects using PSR-0, PSR-1, PSR-2, PSR-4 and namespaces. The project was primarily developed for sabre/dav, but it should work for other codebases as well.

It only documents classes and interfaces.

The code is ugly, it was intended as a one-off, and I was in a hurry.. so the codebase may not be up to your standards. (it certainly isn't up to mine).

Installation

This project assumes you have composer installed. Simply add:

"require-dev" : {

    "evert/phpdoc-md" : "~0.2.0"

}

To your composer.json, and then you can simply install with:

composer install

Usage

First ensure that phpdocumentor 2 is installed somewhere, after, you must generate a file called structure.xml.

The easiest is to create a temporary directory, for example named docs/.

# phpdoc command
phpdoc  -d [project path] -t docs/ --template="xml"

# Next, run phpdocmd:
phpdocmd docs/structure.xml [outputdir]

Options

--lt [template]
    This specifies the 'template' for links we're generating. By default
    this is "%c.md".

--index [filename]
    This specifies the 'filename' for API Index markdown file we're generating.
    By default this is "ApiIndex.md".

This should generate all the .md files. I'm excited to hear your feedback.

Cheers, Evert

phpdoc-md's Issues

Undefined variable: classNames

While parting the structure.xml of two projects which are in a EOL stage (they are now embedded in another project), I got the following notice, which lead to a warning and then to a catchable fatal error.

Basically in Parser::getClassDefinitions the variable $classNames gets initialized only inside the loop, but used outside.

By simply adding $classNames = array(); before the loop, all the issues are gone.

I hope this is the only case, as it's not a good habit to use a variable that might be not initialized.

When PHPDocumentor Markdown generator new version will be released?

Hi I am using PHPDocumentor. But there are several problems with it usage

1. I can not install it via composer as PHPDocumentor requires symfony/event-dispatcher:2.* version, but in project symfony/event-dispatcher:3.4.5 is required. So now I have to phpDocumentor.phar for generating docs.
2. There are some UI issues in the generated template
3. There some warnings reported in console from the source code of PHPDocumentor, like this one
   PHP Warning: count(): Parameter must be an array or an object that implements Countable in phar:///var/platform/dev-utils/phpDocumentor.phar/vendor/twig/twig/lib/Twig/Extension/Core.php on line 1293

And all these problems make me to ask when version 3 of PHPDocumentor will be released?

Bug: Parsing default-values in methods / quotation mark

Single- and double-quotes are not parsed properly:

---

---

Documentation is missing some important data

The same projects as for #7 contains a very lights structure.xml for just one file, with this data:

• File description
• Some PHPDoc for few constant and functions

None of them gets documented.

I get an empty APIIndex.md file (if I exclude the "API Index" heading).

Apparently this script ignores all functions and generic file descriptions: am I right?

PHP Notice: Array to string conversion

Using latest PHPDocumentor and Twig (in PHP 7), a notice is raised:

PHP Notice:  Array to string conversion in \vendor\twig\twig\lib\Twig\Loader\Filesystem.php on line 34

Callstack:

Call Stack:
    0.0002     363344   1. {main}() vendor\evert\phpdoc-md\bin\phpdocmd:0
    0.0140     951672   2. PHPDocMD\Generator->run() \vendor\evert\phpdoc-md\bin\phpdocmd:79
    0.0152     999248   3. Twig_Loader_Filesystem->__construct() \vendor\evert\phpdoc-md\src\Generator.php:76

Checking twig's source code the second parameter is $rootpath but Generator.php is passing a "options array".

Related to #16

Cannot find Generator/Parser libs

Autoload is not included in the repo.

I modified phpdoccmd to add the source directories to the include paths:

// Potential composer autoloader paths
$paths = array(
DIR . '/../vendor/autoload.php',
DIR . '/../../../autoload.php',
'../src/PHPDocMD/Parser.php',
'../src/PHPDocMD/Generator.php',
);

foreach($paths as $path) {
if (file_exists($path)) {
include $path;
}
}

This addressed this particular issue for anyone cloning from this github repo.

Can't run phpdocmd

Hi!

From what I can see, the composer.json file is fine:

{
  "name": "wpml/docs",
  "description": "Build Documentation from PhpDoc comments",
  "minimum-stability": "dev",
  "prefer-stable": true,
  "license": "proprietary",
  "authors": [
    {
      "name": "OnTheGoSystems",
      "email": "[email protected]"
    }
  ],
  "require": {
    "evert/phpdoc-md": "0.1.1"
  }
}

compass install or compass update goes well: no errors or warning.

From the terminal:

$ phpdocmd
bash: phpdocmd: command not found

Same result if I try from a test phpcli script:

<?php
require 'vendor/autoload.php';

exec( 'phpdocmd' );

Result: sh: phpdocmd: command not found

Am I missing something?
I think so, since googling around I couldn't find any single case like mine.

Add twig and parse logic for autoloaded files

Details

You can autoload in files via composer:

"autoload": {
    "files": [
        "src/helpers/api.php",
        "src/helpers/common.php",
        "src/helpers/core.php",
        "src/helpers/debug.php",
        "src/helpers/helpers.php",
        "src/helpers/request.php"
    ]
}

I've created a simple example of one function definition from my generated structure.xml in a gist: https://gist.github.com/ericdowell/6ed8626fac341a213128

Todo

• Create method getFunctionDefintions. Will be similar to what getClassDefinitions does.

  foreach ($xml->xpath('file/function') as $function) {
    //Collect function definition and push into array
  }

• Create similar expandProperties/parseProperties/expandMethods methods for functions. e.g. expandFunctionProperties($filename)/expandFunctionsInFile($filename)/parseFunctionProperties(SimpleXMLElement $file)

• Create function.twig to output function documentation.

Note

I wouldn't mind taking a stab at this addition to the library when my free time permits.

Markers list (TODO / FIXME)

There is a plan for functionality that lists the markers?

Feature Request: Add support for @method documentation

This issue is a feature request to add support for the @method annotation type from PHPDocumentor. These typically occur when dynamically generating methods, and look like this:

/**
 * @method string getString()
 * @method void setInteger(int $integer)
 * @method setString($integer)
 */
class Child extends Parent {
    public function __call() {
        <...>
    }
}

Add StyleCI to correct code style automagically

I would suggest using a new service called StyleCI for correcting any code style. It's free for open source projects.

Incorrect or incomplete usage instructions with phpdoc 2.8.2

pdbogen@mbp-pbogen:~/project-php$ phpdoc parse -t . -d src
Collecting files .. OK
Initializing parser .. OK
Parsing files
Parsing /home/pdbogen/project-php/src/project.php
Storing cache in "/home/pdbogen/project-php" .. OK

..no structure.xml is generated. Is phpdocmd totally incompatible, or is there new syntax to make phpdoc generate a structure.xml?