How to direct solidity-docgen to truffle compiler?

solidity-docgen requires the path to the Solidity compiler from the SOLC_PATH environment variable.

I am actually relying on truffle for compilation. Is there any way to tell solidity-docgen to use the truffle compiler (via solcjs I suppose), or do I now have to download solc executable and set SOLC_PATH to point to its path on my file system?

In fact, why does it even need a compiler to begin with?

I should also note that there are no instructions at https://github.com/OpenZeppelin/solidity-docgen, on how to use this utility.

I had to dig through the source code to this as an initial clue:

  .arguments('<project_path> <contracts_path> <docusaurus_path> [repository_root]')
1 Like

Hi @barakman welcome to the community forum.

npm has a published version 0.1.1 for solidity-docgen whilst the repository is now at 0.2 (alpha)
For details on the change to 0.2 see the Issue: https://github.com/OpenZeppelin/solidity-docgen/issues/23
Version 0.2 uses solcjs: https://github.com/OpenZeppelin/solidity-docgen/pull/17

If you are importing OpenZeppelin then as I understand it you would need to use the 0.1 version as the 0.2 version doesn’t currently support projects with dependencies. https://github.com/OpenZeppelin/solidity-docgen/issues/24

Version 0.1

For help use:
npx solidity-docgen --help

You will need to install solc. https://solidity.readthedocs.io/en/latest/installing-solidity.html#binary-packages

For dealing with imports, follow the instructions https://www.npmjs.com/package/solidity-docgen#dealing-with-imports
Though I was still getting an error “File outside of allowed directories”, though I suspect my setup on Windows Subsystem for Linux might be my problem.

Version 0.2

openzeppelin-solidity uses a slightly later 0.2 version:

https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/package.json

"solidity-docgen": "github:OpenZeppelin/solidity-docgen#03f42b5e271b1e1c1d0b814b921ecdc086055255"

For help use:
npx solidity-docgen --help
I was able to run the same version as used by openzeppelin-solidity to generate documentation for contracts without dependencies:
npx solidity-docgen

Hi @abcoathup.
Thank you for your quick response.

I actually am using v0.1.1, as specified at https://www.npmjs.com/package/solidity-docgen.

But this package seems to have various problems, which make it doubtful that I’ll stick to it.

For once, it relies on the execution of a Unix bash command, so it is generally incompatible with Windows.

The $(find) command in file index.js line 123 cannot be executed on Windows:

var commandOutput = _shelljs2.default.exec(['' + solidityCompilerPath, '  --pretty-json', '  --allow-paths ' + contractsPath, '  --combined-json ' + COMBINED_JSON_OPTIONS.join(','), '  ' + solidityCompilerExtraArgs, '  $(find ' + contractsPath + ' -type f -name "*.sol")'].join(' '), { silent: true });

I proceeded to replace this part with a short snippet (native js) which fetches all source file names recursively.

However, I had to pass those names with their full path (“full” starting from the contracts folder which they are all under). Subsequently, I faced an issue of the compiler with the relative import paths in each one of these source files.

I then realized that I could compile the contracts myself, and then execute only the following lines of code from your tool:

contracts = [an array of objects containing the contents of the output json files]
sources = [an array of strings containing the contents of the input source files]

(0, _generateSidebar2.default)(contracts, contractsPath, excludePaths, docusaurusPath);
(0, _generateDocs2.default)(sources, contractsPath, version, repoBaseUrl, docusaurusPath, repositoryRoot);

However, I haven’t been able to get even that one running (I guess I have possibly failed to initialize correctly either contracts or sources).

So in short, it became increasingly hard to deal with all these problems.

Would you happen to know if version 0.2 is a little more user-friendly by any chance?

Thanks again :slight_smile:

1 Like

If you don’t have dependencies then version 0.2 looks the way forward https://github.com/OpenZeppelin/solidity-docgen/issues/23

What do you mean by “dependencies”?
Does a relative import count as dependency?

OK, I started using it, and it does look more friendly (informative, that is).
However, it emits a ParserError: Source file requires different compiler version (current compiler is 0.5.9...) message on each source file, which is expected considering the fact that my system is currently on 0.4.24.

Running npm ls solc gives me this:

+-- solidity-docgen@0.2.0-alpha.1 (github:OpenZeppelin/solidity-docgen#03f42b5e271b1e1c1d0b814b921ecdc086055255)
| `-- solc@0.5.9
`-- truffle@4.1.14
  `-- solc@0.4.24

I’d be happy to force solidity-docgen@0.2.0-alpha.1 on the same solc version used by truffle@4.1.14.

Is there any way for this to be done (maybe I should just look it up on Google, but just in case you happen to know the answer to that).

Thanks :slight_smile:

1 Like

0.2 version doesn’t currently support projects with dependencies. OpenZeppelin/solidity-docgen#24
e.g. import OpenZeppelin

I haven’t tried relative imports but assume they should be fine.

@abcoathup:

And what about the solc version? Is there any way to force an earlier one (0.4.24 instead of 0.5.9)?

In any case, in order to test your tool, I’ve simply copied the solc folder under the truffle package, and used it to override the one under the solidity-docgen package.

When running node_modules\.bin\solidity-docgen -c path_to_my_contracts, I get:

SyntaxError: Unexpected token o in JSON at position 1
    at JSON.parse (<anonymous>)
    at compile (.....\node_modules\solidity-docgen\dist\gather\solidity\compile.js:50:27)
    at <anonymous>

Line 50 in compile.js is:

  const solcOutput = JSON.parse(solcOutputString);

I printed solcOutputString beforehand, and got:

{ contracts: {},
  errors: [ ':1:1: ParserError: Expected pragma, import directive or contract/interface/library definition.\n ... { ... \n     ^\n' ],
  sourceList: [ '' ],
  sources: {} }

This string is actually the output of the previous line:

  const solcOutputString = _solc.default.compile(JSON.stringify(inputJSON));

And this is the object which is passed to the compile function:

  const inputJSON = {
    language: "Solidity",
    sources: sources,
    settings: compilerSettings
  };

I checked the contents of sources, and it seemed fine. For example, it starts with:

{ 'solidity/contracts/BancorConverterRegistry.sol': { content: 'pragma solidity ^0.4.24;\r\nimport \'./utility/Owned.sol\';...

This one (above) stands for the first file under my contracts folder (solidity/contracts, which is what I pass to solidity-docgen as the value of the -c argument).

For all it matters, the value of the compilerSettings string (or object) is:

{ outputSelection: { '*': { '': [Array], '*': [Array] } } }

Would it be possible for you to have the dev team to take a look at that? (I’ve communicated with nventuro and frangio in the past and they were great, so perhaps one of them might be involved in this project).

Should they be interested to inspect the repo which I am working on, then it is publicly available at https://github.com/bancorprotocol/contracts.

Thanks again :slight_smile:

1 Like

Hi @barakman

To summarize:
You want to generate documentation for the https://github.com/bancorprotocol/contracts
The Bancor contracts use 0.4.24 version of the solc compiler.

solidity-docgen version 0.2 alpha uses solc 0.5.9 which when running solidity-docgen gives an error ParserError: Source file requires different compiler version (current compiler is 0.5.9+commit.e560f70d.Emscripten.clang

Changing the compiler version in solidity-docgen (npm install solc@0.4.24 in node_modules/solidity-docgen) results in error SyntaxError: Unexpected token o in JSON at position 1


I get the same output as you. We will need assistance from the community to solve this one. :smile:

Hi @abcoathup

So I took the role of being a community here, and debugged your code (for example, by manipulating different parts of your input to the compiler, or by comparing your input to the compiler with Truffle’s input to the compiler, etc).

Took several hours, but the bottom-line solution is rather simple.

In file compile.js line 48:

  const solcOutputString = _solc.default.compile(JSON.stringify(inputJSON));

Replace compile with compileStandard.

Together with overwriting the solc folder under /node_modules/solidity-docgen/node_modules with the solc folder under /node_modules/truffle/node_modules (where Truffle version is 4.1.14, which uses Solc version 0.4.24), the above allows me to successfully execute your tool on my contracts.

Thanks!!!

1 Like

Hi @barakman

Thanks for being awesome. Glad you are now generating documentation.

It would be great if you could create an issue with your code fix on the https://github.com/OpenZeppelin/solidity-docgen repository for use with other compiler versions.

@abcoathup:
Thank you, I will do so shortly (including my “hot-fix” executed automatically at the end of npm install, for anyone wishing to make it work with solc 0.4.x, until you guys resolve it in an official manner).

1 Like