can't build project #25
Comments
|
Same issue here... |
|
There's some functional versions floating around that you could modify to meet the needs of your project. https://github.com/ProjectWyvern/wyvern-ethereum --- as part of a larger repo Hopefully one of these might be helpful as there isn't much in the way of doc generators for Solidity at the moment and doxity having been one of the better ones. |
starinje
added a commit
to starinje/doxity
that referenced
this issue
Mar 6, 2018
deprecated tar.gz package was causing an issue (DigixGlobal#25) where the init script would try to copy the gatsby template project over to the destination dir before the tar was completely unpackaged. Fixed the issue by using targz module instead.
|
Still running this problem. |
|
Same problem here: ...
Doxity is initialized! Now run `doxity build`
$ doxity build
/home/nickgeoca/.nvm/versions/node/v10.9.0/lib/node_modules/@digix/doxity/lib/compile/index.js:12
throw new Error('Output directory ' + output + ' not found, are you in the right directory?');
^
Error: Output directory /home/nickgeoca/TokenPoll/scripts/doxity/pages/docs not found, are you in the right directory? |
|
Please pull from the In your solidity project (truffle project or just the .sol contracts)
You can post any further issues, I will assist. You can follow our dao-contracts repository to see how we have done it. |
|
I do so, now i have json files of my conracts in doxity/pages/docs, but when i use ./node_modules/.bin/doxity/publish, i become error: if i add public to scripts/doxity, when publish i become: but this folder is empty. How i can slove this. I do this in truffle project (truffle + webpack unbox), sorry for my bad English(( . |
|
Seriously, if the latest build fixes the issue, why don't you make a new release and fix that for everybody? This makes absolutely no sense. |
|
@sarbogast Nobody is maintaining this repository at present. But I have published the version I am using here: https://www.npmjs.com/package/@digix/doxity-solc |
|
@roynalnaruto Here is what I get when I follow your instructions above: |
|
@sarbogast I have never faced this problem, but may be this is an issue with installing NixOS in MacOS Mojave? NixOS/nix#2244 |
|
Follow your instruction but when i compile i got this error: contract.abi.map is not a function.
|
|
Followed the steps but got the error: |
michalinacienciala
added a commit
to keep-network/tbtc-v2
that referenced
this issue
Mar 8, 2023
We are creating a GH Actions workflow which automatically generates the
contracts documentation based on the functions and the NatSpec-format comments
in the Solidity files stored in the `contracts` folder in
`keep-network/tbtc-v2/solidity`. For certain workflow triggers, the generated
documentation gets published to the `api-docs.threshold.network` preview or main
GCP bucket.
Workflow triggers:
* `workflow_dispatch` - If the worklow gets triggered manually, it will just
build the docs, but will not publish them to the GCP bucket.
* `pull_request` - If the workflow gets triggered by a PR, it will check if the
changes in the PR modify the './.github/workflows/docs.yml' file or files in
the './solidity/contracts' folder. If yes, the workflow will build the HTML
documentation and publish it to the preview GCP bucket
(`api-docs.threshold.network/solidity/<branch_name>`) and will publish a link
to the generated file in the PR's comment.
* 'push' - If the workflow gets triggered by the push to the Solidity release
branch (branch, which name starts with `releases/mainnet/solidity/`), the
workflow will build the HTML documentation and publish it to the preview GCP
bucket (`api-docs.threshold.network/solidity/<branch_name>`).
* `release` - If the workflow gets triggered by the Solidity release (release,
which tag starts with `refs/tags/solidity/`), the workflow will build the HTML
documentation and publish it to the main GCP bucket
(`api-docs.threshold.network/solidity/`).
How HTML documentation gets created:
The documentation gets created based on the content of the Solidity files in
`keep-network/tbtc-v2/solidity`. We first transform it to the Markdown format,
then translate it to Asciidoc and finally, based on that, create an HTML output
file with contracts documentation, which we publish to the GCP bucket. Here is
the description of that process:
1. Before we run the Docgen tool generating Markdown files, we need to perform
some slight changes to the input files, as some of the formatting we use in
our `.sol` files is interpreted by Docgen not the way we would like or is not
completely in line with the NatSpec format:
- In many `@dev` clauses in the Solidity files we have the lists of
requirements or other items which are constructed like this:
```
/// @dev Requirements:
/// - Item one. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
/// Nulla sed porttitor enim, sit amet venenatis enim. Donec tincidunt
/// auctor velit non eleifend. Nunc sit amet est non ligula condimentum
/// mattis.
/// - Item two. Quisque purus massa, pellentesque in viverra tempus,
/// aliquet nec urna.
```
This doesn't get recognized by Docgen as a list and is translated to
regular text, which is displayed as one continuous line. But when the space
characters between `///` and the text get removed from he `.sol` files, the
lists are recognized correctly (without breaking interpretation of other
features). That's why we decided to run `sed -i 's_///[[:blank:]]*_///_'`
command on all Solidity files.
- In one line of the `BitcoinTx.sol` file there's an incorrectly used `//`
comment inside the `@dev` clause, which makes the Docgen think think that
the clause is ending in the line with `//` (which results in wierd and
incomplete display of the description of the `BitcoinTx` function). Due to
that we are removing the problematic line from the file before running
Docgen by running `sed -i ':a;N;$!ba;s_///\n//\n_///\n_g'` on the file.
2. Once the files are ready, we use the Docgen tool
(https://github.com/OpenZeppelin/solidity-docgen) to generate Markdown
`index.md` file with the contracts documentation. The tool is
configured to
- export the documentation of all contracts into one common file (default
behavior),
- place the generated file into `generated-docs` folder,
- don't generate documentation for contracts in the `contracts/test` folder
(as those are test/stub contracts which are not used on Mainnet),
- use custom template for Markdown generation (based on the default
https://github.com/OpenZeppelin/solidity-docgen/blob/master/src/themes/markdown/common.hbs
template, but with removed italicisation of the `{{{natspec.dev}}}` element
- because it wasn't working well with the lists in the `@dev` clauses).
3. Then we transform the `index.md` Markdown file into `tbtc-v2-contracts.adoc`
Asciidoc file using tool called Kramdoc-AsciiDoc
(https://github.com/asciidoctor/kramdown-asciidoc).
4. Next we inject two lines at the beginning of that file, to add the table of
contens:
```
:toc: left
:toclevels: 1
```
5. Once that is done, we build the `tbtc-v2-contracts.html' HTML file using
custom `thesis/asciidoctor-action` GH Acion. The action generates that file
into `./asciidoc-out/solidity/generated-docs` folder.
6. We then use `thesis/gcp-storage-bucket-action` to push the content of that
folder to the `api-docs.threshold.network/solidity` main GCP bucket (or
`api-docs.threshold.network/solidity/<branch_name>` preview GCP bucket)
Alternative tools for Solidity documentation generation that were considered:
* Doxity (https://github.com/DigixGlobal/doxity) - I tried to use it, but hit a
bunch of issues during installation - some of which I resolved, but got stuck
on DigixGlobal/doxity#25. The project is not
maintained anymore, latest commits are from year 2017. I figured that
exploring the tool more and trying to find a workaround for the issue I
observed may be a waste of time.
* Dodoc (https://github.com/primitivefinance/primitive-dodoc) - yields similar
results as Docgen (although slightly worse - some @dev/@notice comments were
not displayed at all), but does not have an option to output the documentation
to one combo file - each .sol file generates a single .md file.
* Solidoc (https://github.com/binodnp/solidoc) - operates on .NET, I haven't
explored that tool
* Remix IDE plugin (https://remix-ethdoc-plugin.readthedocs.io/en/latest/) - I
don't use Remix IDE, also I don't think we could use this plugin in automation
* Hardhat Docgen (https://www.npmjs.com/package/hardhat-docgen) - I already had
most of the work with my workflow done when I learned about this tool. I tried
it on, but hit errors when running `hardhat-compile`. Couldn't find a quick
solution, decided not to investigate further.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
I have an existing solidity project that I can't gen comments and api for. Followed directions and this is what I got:
Getting https://github.com/DigixGlobal/doxity-gatsby-starter-project/archive/a4886b7a7a04c018ac04fed3125d7d4785e74bed.tar.gz...
⣟ Setting up doxity project with npm install. This may take a while...npm WARN [email protected] No description
up to date in 0.099s
Doxity is initialized! Now run
doxity build/usr/local/lib/node_modules/@digix/doxity/lib/compile/index.js:12
throw new Error('Output directory ' + output + ' not found, are you in the right directory?');
^
Error: Output directory /Users/kevin/Desktop/BlockChain/layer1/blockchain/scripts/doxity/pages/docs not found, are you in the right directory?
at exports.default (/usr/local/lib/node_modules/@digix/doxity/lib/compile/index.js:12:11)
at Object.exports.default [as build] (/usr/local/lib/node_modules/@digix/doxity/lib/build.js:8:25)
at Object.wrappedMethods.(anonymous function) [as build] (/usr/local/lib/node_modules/@digix/doxity/lib/index.js:71:24)
at Object. (/usr/local/lib/node_modules/@digix/doxity/lib/bin/doxity.js:35:28)
at Module._compile (module.js:660:30)
at Object.Module._extensions..js (module.js:671:10)
at Module.load (module.js:573:32)
at tryModuleLoad (module.js:513:12)
at Function.Module._load (module.js:505:3)
at Function.Module.runMain (module.js:701:10)
at startup (bootstrap_node.js:194:16)
at bootstrap_node.js:618:3
The text was updated successfully, but these errors were encountered: