• Add a proper file header doc block including stating the license etc.
• Add doc bocks to functions and attributes

See http://keepachangelog.com/

https://help.github.com/articles/setting-guidelines-for-repository-contributors/
https://github.com/blog/1184-contributing-guidelines

It seems raml2html is not yet a package published to Packagist.

https://packagist.org/search/?q=raml2html

As people could need to use certain versions of raml2html for different projects, it would be beneficial for them to have a package on Packagist.

Also if people want to extend your code, it would make their lives much easier.

Here is some how to:
https://packagist.org/about

If you need help with that, I'll be happy to assist.

https://getcomposer.org/doc/articles/versions.md#caret

I'm getting this error when attempting to generate (RAML 1.0):

Warning: Invalid argument supplied for foreach() in phar:///usr/local/bin/raml2html/vendor/cnam/php-raml-parser/src/Parser.php on line 614

Warning: Invalid argument supplied for foreach() in phar:///usr/local/bin/raml2html/vendor/cnam/php-raml-parser/src/Parser.php on line 614

Warning: Invalid argument supplied for foreach() in phar:///usr/local/bin/raml2html/vendor/cnam/php-raml-parser/src/Parser.php on line 614

Catchable fatal error: Argument 2 passed to Raml\NamedParameter::createFromArray() must be of the type array, string given, called in phar:///usr/local/bin/raml2html/vendor/cnam/php-raml-parser/src/SecurityScheme/SecuritySchemeDescribedBy.php on line 102 and defined in phar:///usr/local/bin/raml2html/vendor/cnam/php-raml-parser/src/NamedParameter.php on line 216

My security scheme description is:

securitySchemes:
    - passthrough:
        description: This API supports PassThrough Authentication using either the query parameter "token" or header "X-API-KEY".
        type: PassThrough
        describedBy:
            queryParameters:
                token: string
            headers:
                X-API-KEY: string
            responses:
                403:
                    description: Bad token.

It would be great, if you added raml 1.0 features support. Thanks!

It is not necessary to include

• build
• example
• composer.json
• composer.lock
• ohter files related only to the development

Allow to use a custom template or allow to override certain parts of the documentation.

If this is already possible, please add documentation for it.

I am trying to run the builder from docker image (just like mentioned in README.md):

docker run  \
   -v `pwd`:/data \
   leanlabs/raml-doc-builder \
   generate --input=API.raml --output=API.html

.. and this is the error that I get:

Unable to find image 'leanlabs/raml-doc-builder:latest' locally
docker: Error response from daemon: repository leanlabs/raml-doc-builder not found: does not exist or no pull access.

My RAML spec includes schema files located in a subdirectory:

.
├── my_api.raml
└── schema
    ├── some_schema.jss

Generation fails with:

failed to open stream: No such file or directory in /{snip}/raml2html-php/vendor/justinrainbow/json-schema/src/JsonSchema/Uri/Retrievers/FileGetContents.php on line 36
JSON schema not found at file:///{path to raml dir}/some_schema.jss

although RAML contains:

schemas:
  - some-schema:        !include schema/some_schema.jss

i.e. the schema sub-path is there but is ignored by the generator.

with v0.8 valid RAML like:

      [
        sortable: { fieldsList: 'firstname, lastname, activeState, employeeNo' },
        pageable
      ]

you get the following parse error:

Unable to parse at line 343 (near "[").
/Users/rrrw/Projects/contrib/raml/raml2html/vendor/symfony/yaml/Parser.php 298
#0 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/symfony/yaml/Parser.php(225): Symfony\Component\Yaml\Parser->parse('[\n  sortable: {...', true, true, false)
#1 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/symfony/yaml/Parser.php(225): Symfony\Component\Yaml\Parser->parse('is:\n  [\n    sor...', true, true, false)
#2 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/symfony/yaml/Parser.php(225): Symfony\Component\Yaml\Parser->parse('type:\n  collect...', true, true, false)
#3 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/symfony/yaml/Yaml.php(68): Symfony\Component\Yaml\Parser->parse('#%RAML 0.8\ntitl...', true, true, false)
#4 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/cnam/php-raml-parser/src/Parser.php(507): Symfony\Component\Yaml\Yaml::parse('#%RAML 0.8\ntitl...', true, true)
#5 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/cnam/php-raml-parser/src/Parser.php(478): Raml\Parser->parseYaml('#%RAML 0.8\ntitl...')
#6 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/cnam/php-raml-parser/src/Parser.php(209): Raml\Parser->parseRamlString('#%RAML 0.8\ntitl...', '/Users/rrrw/Pro...', true)
#7 /Users/rrrw/Projects/contrib/raml/raml2html/src/Generator.php(55): Raml\Parser->parse('/Users/rrrw/Pro...', true)
#8 /Users/rrrw/Projects/contrib/raml/raml2html/src/Command/GenerateCommand.php(62): Cnam\Generator->parse('/Users/rrrw/Pro...')
#9 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/symfony/console/Command/Command.php(259): Cnam\Command\GenerateCommand->execute(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#10 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/symfony/console/Application.php(844): Symfony\Component\Console\Command\Command->run(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#11 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/symfony/console/Application.php(192): Symfony\Component\Console\Application->doRunCommand(Object(Cnam\Command\GenerateCommand), Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#12 /Users/rrrw/Projects/contrib/raml/raml2html/vendor/symfony/console/Application.php(123): Symfony\Component\Console\Application->doRun(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#13 /Users/rrrw/Projects/contrib/raml/raml2html/raml2html(29): Symfony\Component\Console\Application->run()
#14 {main}

The responsive behavior of the template does not work well with browser screen width less than around 1200px.

When I generate the HTML for my RAML with release 0.0.5, it generates me a working API documentation.
When I try it with the new release 0.0.6, it's broken.

When I run: raml2html.phar -i api.raml -o /tmp/api.html

I receive:

                     
  [InvalidArgumentException]          
  Command "api.raml" is not defined.  

although the api.raml file exists...

Without uppercase the resources are more readable:

At best the MIT License

See:
https://github.com/blog/1530-choosing-an-open-source-license
http://choosealicense.com/

This will lead to cleaner code and releases with less hassle.

I'm trying to generate the doc for this RAML: https://api.unbounce.com/raml/v0.4/api.raml

Here is the error I get:

array(1) {
  ["schema"]=>
  string(3008) "{"$schema":"http:\/\/json-schema.org\/draft-04\/schema#","description":"Collection of account entities.","type":"object","additionalProperties":false,"required":["accounts","metadata"],"properties":{"accounts":{"type":"array","minItems":0,"uniqueItems":true,"items":{"$schema":"http:\/\/json-schema.org\/draft-04\/schema#","description":"TODO describe","type":"object","additionalProperties":false,"required":["created_at","id","metadata","name","options","state"],"properties":{"created_at":{"title":"Generic Date","description":"RFC 5322, section 3.4.1, compliant date, which means formatted with: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'","type":"string","format":"date-time","id":"file:\/\/\/home\/ddossot\/dev\/projects\/ub-public-api-specs\/resources\/webroot\/raml\/v0.4\/schema\/common\/definitions_v2.0.json#\/date"},"id":{"type":"string"},"metadata":{"type":"object","allOf":[{"title":"Entity Metadata","type":"object","required":["location","documentation"],"properties":{"location":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"},"related":{"type":"object"}},"id":"file:\/\/\/home\/ddossot\/dev\/projects\/ub-public-api-specs\/resources\/webroot\/raml\/v0.4\/schema\/common\/entities_v2.0.json#\/entity_metadata"},{"type":"object","required":["related"],"properties":{"related":{"type":"object","additionalProperties":false,"required":["pages","accounts","sub_accounts"],"properties":{"pages":{"type":"string","format":"uri"},"accounts":{"type":"string","format":"uri"},"sub_accounts":{"type":"string","format":"uri"}}}}}],"id":"file:\/\/\/home\/ddossot\/dev\/projects\/ub-public-api-specs\/resources\/webroot\/raml\/v0.4\/schema\/metadata.json#\/account_metadata"},"name":{"type":"string"},"options":{"$schema":"http:\/\/json-schema.org\/draft-04\/schema#","type":"object","additionalProperties":false,"properties":{"api_keys_enabled":{"type":"boolean"}},"id":"file:\/\/\/home\/ddossot\/dev\/projects\/ub-public-api-specs\/resources\/webroot\/raml\/v0.4\/schema\/account_options.json"},"state":{"type":"string","enum":["active","suspended"]}},"id":"file:\/\/\/home\/ddossot\/dev\/projects\/ub-public-api-specs\/resources\/webroot\/raml\/v0.4\/schema\/account.json"}},"metadata":{"title":"Collection Metadata","type":"object","allOf":[{"title":"Entity Metadata","type":"object","required":["location","documentation"],"properties":{"location":{"type":"string","format":"uri"},"documentation":{"type":"string","format":"uri"},"related":{"type":"object"}},"id":"file:\/\/\/home\/ddossot\/dev\/projects\/ub-public-api-specs\/resources\/webroot\/raml\/v0.4\/schema\/common\/entities_v2.0.json#\/entity_metadata"},{"type":"object","required":["count"],"properties":{"count":{"type":"integer"}}}],"id":"file:\/\/\/home\/ddossot\/dev\/projects\/ub-public-api-specs\/resources\/webroot\/raml\/v0.4\/schema\/common\/entities_v2.0.json#\/collection_metadata"}},"id":"file:\/\/\/home\/ddossot\/dev\/projects\/ub-public-api-specs\/resources\/webroot\/raml\/v0.4\/schema\/accounts.json"}"
}
The key application/vnd.unbounce.api.v0.4+json does not exist.
phar:///home/ddossot/dev/tools/raml2html.phar/vendor/cnam/php-raml-parser/src/Parser.php 333
#0 phar:///home/ddossot/dev/tools/raml2html.phar/vendor/cnam/php-raml-parser/src/Parser.php(336): Raml\Parser->recurseAndParseSchemas(Array, '/home/ddossot/d...')
#1 phar:///home/ddossot/dev/tools/raml2html.phar/vendor/cnam/php-raml-parser/src/Parser.php(336): Raml\Parser->recurseAndParseSchemas(Array, '/home/ddossot/d...')
#2 phar:///home/ddossot/dev/tools/raml2html.phar/vendor/cnam/php-raml-parser/src/Parser.php(336): Raml\Parser->recurseAndParseSchemas(Array, '/home/ddossot/d...')
#3 phar:///home/ddossot/dev/tools/raml2html.phar/vendor/cnam/php-raml-parser/src/Parser.php(336): Raml\Parser->recurseAndParseSchemas(Array, '/home/ddossot/d...')
#4 phar:///home/ddossot/dev/tools/raml2html.phar/vendor/cnam/php-raml-parser/src/Parser.php(273): Raml\Parser->recurseAndParseSchemas(Array, '/home/ddossot/d...')
#5 phar:///home/ddossot/dev/tools/raml2html.phar/vendor/cnam/php-raml-parser/src/Parser.php(211): Raml\Parser->parseRamlData(Array, '/home/ddossot/d...', true)
#6 phar:///home/ddossot/dev/tools/raml2html.phar/src/Generator.php(55): Raml\Parser->parse('/home/ddossot/d...', true)
#7 phar:///home/ddossot/dev/tools/raml2html.phar/src/Command/GenerateCommand.php(62): Cnam\Generator->parse('/home/ddossot/d...')
#8 phar:///home/ddossot/dev/tools/raml2html.phar/vendor/symfony/console/Symfony/Component/Console/Command/Command.php(257): Cnam\Command\GenerateCommand->execute(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#9 phar:///home/ddossot/dev/tools/raml2html.phar/vendor/symfony/console/Symfony/Component/Console/Application.php(874): Symfony\Component\Console\Command\Command->run(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#10 phar:///home/ddossot/dev/tools/raml2html.phar/vendor/symfony/console/Symfony/Component/Console/Application.php(195): Symfony\Component\Console\Application->doRunCommand(Object(Cnam\Command\GenerateCommand), Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#11 phar:///home/ddossot/dev/tools/raml2html.phar/vendor/symfony/console/Symfony/Component/Console/Application.php(126): Symfony\Component\Console\Application->doRun(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#12 phar:///home/ddossot/dev/tools/raml2html.phar/index.php(15): Symfony\Component\Console\Application->run()
#13 /home/ddossot/dev/tools/raml2html.phar(10): include('phar:///home/dd...')
#14 {main}