Three steps to document Solididty in SPHINX

I was able to get solidity docgen working by implementing a series of three different stages all automated in our build process.

1. Parse the solc output into actual json.
2. Load the json file into the documentation system
3. Use a Jinja template to convert the api document

There is shockingly poor support for docgen in Solidity. Although it is possible to document your code in NatSpec, one quickly discovers this is a trap.

The only output format available in solc is json. And unfortunately that is not even actual json but a hybridized text and json log.

It is apparent that a document generation phase is required. However, after exploring all the available document generation tools available, there are many problems and challenges. Many of the existing tools do not build with latest versions. Several have not been updated for 5 years or never worked all. Thus it is a major challenge to publish docs from a solidity codebase.

To do it my way, first, invoke solc to generate the document log.

$ solc --devdoc --userdoc --include-path node_modules/ --base-path . contracts/* > ${DOCFILE}

Now ${DOCFILE} contains the document spec data. We want to parse this into json that a programmatic system can parse.

This script is invoked as follows:

parse_solcdoc.py ${DOCFILE} ${GENERATED_DOCFILE}

Finally this generated json can be used to build a contract specification from a template in SPHINX. Once you have configured your main site. The ${GENERATED_DOCFILE} can simply be loaded into the SPHINX conf.py.

I used the following code:

This can be added to the sphinx setup hook in conf.py.

def setup(app):
    """
    sphinx setup hook
    """
    load_automated_docgen()    

The last step is to build a jinja template to output the automated docgen data in human readable format. I used an api template in ReStructured Text:

By combining these stages as part of out automated build we are able to produce generated documentation for our contracts.

The resulting Documentation Site

Collective Governance smart contract.