Generate docs directly from solc output file

[adrake33]

We tried to use solidity-docgen to generate docs for Augur, but we were encountering some errors and decided the quickest workaround to get it to work with our contracts would be to directly import the solc JSON file instead of having solidity-docgen do the compiling. (I ended up creating a quick and dirty hack for this at https://github.com/AugurProject/solidity-docgen.)

It would be great if a similar option could be added to solidity-docgen to specify a JSON file to use in order to bypass the compiling process.

CC @pgebheim

[pgebheim]

Thanks @adrake33

@frangio -- wonder how we can help here? Is the approach of giving an option to just read the solc output json from a file one that you think you'd wanna add to the project proper?

[frangio]

I'm very happy to see that you guys were able to implement the feature, even if a quick and dirty hack! I'm sure you've also noticed that the code is a bit of a mess. :slightly_smiling_face: It desperately needs a refactor, but I haven't gotten around to it yet. I don't feel comfortable adding this feature before the rest of the codebase is improved at least a bit, because I can think of a few things related to this feature that would benefit from those improvements.

What was exactly the problem you ran into with the compiler? Were you able to get it working in the end?

[pgebheim]

Our build process is boutique since we have sooo many contracts.

@adrake can post the error, but the simple impl of building all the *.sol files just failed.

Paul

---

From: Francisco Giordano [email protected] Sent: Wednesday, June 5, 2019 3:39:39 PM To: OpenZeppelin/solidity-docgen Cc: Paul Gebheim; Mention Subject: Re: [OpenZeppelin/solidity-docgen] Generate docs directly from solc output file (#28)

I'm very happy to see that you guys were able to implement the feature, even if a quick and dirty hack! I'm sure you've also noticed that the code is a bit of a mess. 🙂 It desperately needs a refactor, but I haven't gotten around to it yet. I don't feel comfortable adding this feature before the rest of the codebase is improved at least a bit, because I can think of a few things that would benefit from those improvements.

What was exactly the problem you ran into with the compiler? Were you able to get it working in the end?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHubhttps://github.com/OpenZeppelin/solidity-docgen/issues/28?email_source=notifications&email_token=AAAU76VEQ57AXWR5XXCHZLTPZA6CXA5CNFSM4HUFNWDKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODXBHAVQ#issuecomment-499282006, or mute the threadhttps://github.com/notifications/unsubscribe-auth/AAAU76XKHFQZWKHNC3ZSZPLPZA6CXANCNFSM4HUFNWDA.

[adrake33]

The original error I was getting was

'Uncaught fatal error: /root/project/liblangutil/ErrorReporter.cpp(114): Throw in function bool langutil::ErrorReporter::checkForExcessiveErrors(Error::Type)\nDynamic exception type: boost::exception_detail::clone_impl<langutil::FatalError>\nstd::exception::what: std::exception\n',

It wasn't entirely clear what was causing this, so I copied over some of our code for compiling our contracts into compile.js, and I got close to getting it working. However, I was still getting a JSON parsing error, so I modified the code to accept a solc JSON output file instead. Given more time, I'm sure I could eventually figure out the JSON parsing error, but at the moment I'm not sure what was causing it.

One other suggestion I have, though, would be to allow the user to add remappings to the compiler settings. For example, all of the imports in our contract imports look like import 'ROOT/reporting/IMarket.sol'; As a result, I had to hard code remappings: [ `ROOT=${directory}/`], into compile.js. It'd be great if the user could somehow specify their own custom compiler settings.

[frangio]

Hey guys, I am working on a refactor/rewrite in the refactor branch. It is much more robust.

I would like to fix your issue. What is the repository with the contracts you want to generate docs for?

[pgebheim]

Our contracts are in

https://github.com/AugurProject/augur/tree/master/packages/augur-core/src/contracts (https://link.getmailspring.com/link/[email protected]/0?redirect=https%3A%2F%2Fgithub.com%2FAugurProject%2Faugur%2Ftree%2Fmaster%2Fpackages%2Faugur-core%2Fsrc%2Fcontracts&recipient=cmVwbHkrQUFBVTc2U1BCTFhHTVU2V0pTNVg1S0YzRU9LVVJFVkJOSEhCVjYzMlNFQHJlcGx5LmdpdGh1Yi5jb20%3D) Our code to build the contracts is custom and sits in the src/libraries/ContractCompiler.ts class On Jun 28 2019, at 11:56 am, Francisco Giordano [email protected] wrote:

Hey guys, I am working on a refactor/rewrite in the refactor (https://link.getmailspring.com/link/[email protected]/1?redirect=https%3A%2F%2Fgithub.com%2FOpenZeppelin%2Fsolidity-docgen%2Ftree%2Frefactor&recipient=cmVwbHkrQUFBVTc2U1BCTFhHTVU2V0pTNVg1S0YzRU9LVVJFVkJOSEhCVjYzMlNFQHJlcGx5LmdpdGh1Yi5jb20%3D) branch. It is much more robust.

I would like to fix your issue. What is the repository with the contracts you want to generate docs for? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub (https://link.getmailspring.com/link/[email protected]/2?redirect=https%3A%2F%2Fgithub.com%2FOpenZeppelin%2Fsolidity-docgen%2Fissues%2F28%3Femail_source%3Dnotifications%26email_token%3DAAAU76U47HKHHOHNGAW74G3P4ZNERA5CNFSM4HUFNWDKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODY2425I%23issuecomment-506842485&recipient=cmVwbHkrQUFBVTc2U1BCTFhHTVU2V0pTNVg1S0YzRU9LVVJFVkJOSEhCVjYzMlNFQHJlcGx5LmdpdGh1Yi5jb20%3D), or mute the thread (https://link.getmailspring.com/link/[email protected]/3?redirect=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAAAU76WTPJFHHCOXLXSPKNTP4ZNERANCNFSM4HUFNWDA&recipient=cmVwbHkrQUFBVTc2U1BCTFhHTVU2V0pTNVg1S0YzRU9LVVJFVkJOSEhCVjYzMlNFQHJlcGx5LmdpdGh1Yi5jb20%3D).

[mr-ubik]

Are there any updates on this?

[frangio]

The feature hasn't been implemented. The codebase was entirely rewritten since the original issue was opened so the patches no longer apply. The tool is much more robust, though, so I wonder if the same errors would show up.

@mr-ubik If you ran into any specific issues please open issues so we can troubleshoot. (Other than the issues you have already opened.)

I do think this feature is a good idea, though. There just hasn't been pressure to implement it.

[ghost]

Is that something still planed?

[frangio]

I still think this is a good idea, but there are no plans to do this. If someone wants to take it on I'm happy to guide through it.