Documenting and updating
To put metadata into our functions we will follow the python standards and use docstrings and type hints. These are widely used throughout the python ecosystem, and so as well as informing ArupCompute they will also help populate editors with help text, and can be used to auto-generate standalone documentation.
Basic meta-data
Update your function to look like this:
def add(a: float, b: float) -> float:
"""Add
Adds two decimal numbers together.
Args:
a: The first number
b: The second number
Returns:
x: The addition of the two numbers
"""
x = a + b
return x
The inputs are annotated with their types a: float. This helps improve the robustness of the ArupCompute system by ensuring that the data sent by the user is converted into the correct type.
The output of the function is also annotated -> float, again to improve system robustness.
The docstrings are contained within triple quotes at the start of the file """.
The first line is the title of the function, this is the name that will be displayed to users in the various ArupCompute interfaces.
The subsequent line(s) are a description. This is the only information that a user will have to decide whether your function is relevant to them, so be as descriptive as possible.
The two subsequent sections define further information about the inputs and outputs. The descriptions provided here will be used as tooltips to the inputs in the various ArupCompute interfaces.
Whilst there is more information we can provide, for now lets reupload our library to see how things look.
Updating a library
Zip up your folder of files again and then find your library on ArupCompute. As the library author you will be presented with an additional pencil button that allows the library to be updated.
Click on this button and you will be presented with the same upload form we saw before. Select 'python' as the language again, and then on the third page most of the inputs will be pre-filled. The only input we need to update is the version. Use semver notation to describe the magnitude of the change. In this case we are just improving documentation rather than changing functionality so its a PATCH level change.
Click on 'browse' and select your new zip file.
Press upload, and then perhaps go grab a coffee whilst it works its way through AC's publishing system!
Reviewing the meta-data
Navigate to the updated version of your library and things will be looking much better.
There is much more meta-data that can be added to your functions to make them easier to use:
- Tell the user what units the inputs should be in
- Use KaTeX typesetting to provide better typesetting for inputs, including greek letters, subscripts and superscripts
- Provide a list of assumptions
- Give links to reference documentation