Automatic Documentation Generation from Solidity Source¶
Configuration¶
By default, sphinxcontrib.soliditydomain
assumes that associated Solidity source files may be found in the directory ../contracts
relative to the root of the Sphinx project:
. # project root
├── docs/ # root of the Sphinx project
├── contracts/ # root of all contracts
└── ...
This may be changed with the following configuration variable:
-
autodoc_lookup_path
A path to Solidity files to be indexed for autodocumentation purposes. By default, this is
../contracts
relative to the documentation directory.
Note
sphinxcontrib.soliditydomain
will crawl the contract lookup directory, collecting .sol
files, parsing the source content with an ANTLR 4 parser using this Solidity grammar definition, and building a database of Solidity language objects for which the documentation tool will be able to automatically generate documentation.
Note
If a Solidity source file cannot be parsed by this package, a warning will be issued and the Sphinx build will continue trying to build the rest of the documentation.
Autodoc Directives By Example¶
All of the formatting directives admit corresponding autodocumentation directives accessible by prepending autosol
to the formatting directive name.
Let’s suppose that the following code is found in a Solidity source file:
pragma solidity ^0.4.24;
library DaHood {
enum Coast { East, West }
}
/// @title A simulator for Bug Bunny, the most famous Rabbit
/// @author Warned Bros
contract BugBunny {
/// Hash of a carrot. You can use triple forward slashes (``///``)
/// to have Solidity Domain pull the docs out of the comment.
/**
* Comment blocks starting with ``/**`` will also be added to documentation.
* These blocks may be framed with a preceding ``*`` on each line.
*/
bytes32 public carrotHash;
mapping (address => mapping (uint => bool)) public ballerz;
event Consumption(address indexed feeder, string food);
event Consumption(address indexed payer, uint amount);
/// Doxygen-style tags on events currently unsupported by devdocs
/// but will work here.
/// @param coast The original beef.
event AnonEvent(DaHood.Coast coast) anonymous;
/// Constructor for BugBunny. Note that solc doesn't parse
/// Doxygen-style devdocs for these, but this is supported
/// in this plugin.
/// @param carrot Eh... what's up, doc?
constructor(string carrot) public {
carrotHash = keccak256(abi.encodePacked(carrot));
}
/// @author Birb Lampkett
/// @notice Determine if Bug will accept `_food` to eat
/// @dev String comparison may be inefficient
/// @param _food The name of a food to evaluate (English)
/// @return true if Bug will eat it, false otherwise
function doesEat(string _food) public view returns (bool) {
return keccak256(abi.encodePacked(_food)) == carrotHash;
}
/// @author Funk Master
/// @dev Magic funk machine wow.
/// @param _food The name of a food to eat
/// @return {
/// "eaten": "true if Bug will eat it, false otherwise",
/// "hash": "hash of the food to eat"
/// }
function eat(string _food) public returns (bool eaten, bytes32 hash) {
eaten = doesEat(_food);
hash = keccak256(abi.encodePacked(_food));
if(eaten) {
emit Consumption(msg.sender, _food);
}
}
/// @notice Bug will eat either `food1` or `food2`
/// @dev Raw stuff.
/// @param food1 The name of first food to try
/// @param food2 The name of second food to try
/// @return {
/// "eaten": "true if Bug ate, false otherwise",
/// "hash": "hash of the food eaten"
/// }
function eat(string food1, string food2) external returns (bool eaten, bytes32 hash) {
if(doesEat(food1)) {
(eaten, hash) = eat(food1);
} else {
(eaten, hash) = eat(food2);
}
}
// tags on fallback functions currently not supported by devdocs
function() external payable {
emit Consumption(msg.sender, msg.value);
ballerz[msg.sender][msg.value] = true;
}
}
The following directives may be used:
-
.. autosolcontract::
Name
¶ -
.. autosollibrary::
Name
¶ -
.. autosolinterface::
Name
¶ These directive require the targetted object’s name and will render to a corresponding
sol:contract
,sol:library
, orsol:interface
block. The following ReST:.. autosolcontract:: BugBunny
will render like so:
-
contract
BugBunny
¶ Title: A simulator for Bug Bunny, the most famous Rabbit Author: Warned Bros
Furthermore, the
:noindex:
,:members:
and:exclude-members:
options may be used as expected, with.. autosolcontract:: BugBunny :noindex: :members: doesEat, constructor
yielding
-
contract
BugBunny
Title: A simulator for Bug Bunny, the most famous Rabbit Author: Warned Bros -
constructor
(string carrot)
public Constructor for BugBunny. Note that solc doesn’t parse Doxygen-style devdocs for these, but this is supported in this plugin.
Parameters: - carrot – Eh… what’s up, doc?
-
function
doesEat
(string _food)
public
view
returns (bool) String comparison may be inefficient
Author: Birb Lampkett
Notice: Determine if Bug will accept _food to eat
Parameters: - _food – The name of a food to evaluate (English)
Return: true if Bug will eat it, false otherwise
-
and
.. autosolcontract:: BugBunny :noindex: :members: :exclude-members: ballerz, Consumption, eat, doesEat, <fallback>
yielding
-
contract
BugBunny
Title: A simulator for Bug Bunny, the most famous Rabbit Author: Warned Bros -
bytes32 public
carrotHash
Hash of a carrot. You can use triple forward slashes (
///
) to have Solidity Domain pull the docs out of the comment.Comment blocks starting with
/**
will also be added to documentation. These blocks may be framed with a preceding*
on each line.
-
event
AnonEvent
(DaHood.Coast coast)
anonymous Doxygen-style tags on events currently unsupported by devdocs but will work here.
Parameters: - coast – The original beef.
-
constructor
(string carrot)
public Constructor for BugBunny. Note that solc doesn’t parse Doxygen-style devdocs for these, but this is supported in this plugin.
Parameters: - carrot – Eh… what’s up, doc?
-
bytes32 public
Note
Contract members will appear in the order they were indexed by the Solidity source crawler.
-
contract