Generating Documentation

Properly testing your extensions is a great practice to get into, but documenting what you've created is also essential. Just like writing tests, writing documentation can be a real bummer, so lolpop is here again to leverage generative AI to try to automate your way through this. Let's take a look.

Automating Extension Docstrings¶

Writing good docstrings can help others better understand how to use your code, or at least how you intended for it to be used. However, it's not uncommon to plow through development without creating docstrings and once the project is nearing completion adding them to dozens or hundreds of methods can be a larger task than we'd like to undertake and it's easy to just skip over it (Note: hooray for pre-commit hooks that enforce docstring use!).

lolpop is here to help guide you through the drudgery and help automate docstring creation. You can begin creating docsstrings for your methods via the following command:

lolpop create docstrings <source_file> <class_name> --output-path my_extension_docstrings.py

The above command will write docstrings for all methods of the given extension class_name in the provided source_file and save the resulting tests to the --output-path.

Note that for small classes your returned text from generative AI may be a direct replacement for your existing class (i.e. ChatGPT does the docstrings in place), whereas for larger classes you will likely just get a shell that you'll need to copy and paste back into the original document.

Note

Just like with tests, generative AI is not failproof with respect to writing docstrings. In our experience it will do a pretty great job of identifying all necessary inputs and outputs, as well as writing a concise description for what your method does, but it may struggle to correctly identify proper data types.

Customizing Docstring Generation¶

The code for docstring generation is nearly identical to that of test generation, so the cusotmizations are all the same: --method-filter, --generator-class, --docstring-format etc. Feel free to consult lolpop create docstrings --help for more information.

Automating Extension Docs¶

We can additionally use lolpop to generate documentation for our extension. The command should look familiar:

lolpop create documentation <source_file> <class_name> --output-path my_extension_documentation.md

The above command will write documentation for the given extension class_name in the provided source_file and save the resulting tests to the --output-path as a markdown file.

Of all the generative AI methods that lolpop exposes, documentation generation is currently the most hit and miss. A few tips that might help get better results:

Generate docstrings for all methods before generating documentation. This seems to help the AI better understand whats' going on.
Comment your code. Hey, it's a good practice anyway.
Try to use standard imports. I.E. import pandas as pd will resonate more w/ the AI than import pandas as sklearn.
If you're creating really large classes, try breaking them into a few smaller classes for the sake of generating documentation and them combine them afterwards.

In our experience, documentation tends to be accurate, but incomplete. It likely needs a few rounds of iteration to get right and the zero-shot approach we're currently using may be improved upon in future releases. Feel free to hone this approach in your own extension and let us know if you get great results.

Customizing Documentation Generation¶

Your invocation of the lolpoop create documentation can be customized via the standard --method-filter, --generator-class, and --documentation-format.

Proposed Documentation Structure¶

While the structure of documentation should conform to the standard of your own organizaiton, we believe the following is concise and easy to grok for lolpop use:

<integration description>

## Configuration

### Required Configuration

<list of required configuration and a description of each>

### Optional Configuration 

<list of optional configuration and a description of each>

### Default Configuration

<list of default configuration, a description of each, and the default values>

## Attributes

<A list of all attributes used> 
#Note: attributes are generally atypical in lolpop, as integrations usually rely on configuration over hard-coded attributes.

## Methods

<a list of all available methods>

<For each method:>

### Method Name

<method signature>

<list of method arguments and a description of each>

<list of method outputs and a description of each >

<a example of using the method in code>