MHKiT-MATLAB
MHKiT-MATLAB copied to clipboard
Feature: Fix and add test for incorrectly formatted docstrings
Status: Ready for Review
Add docstring validation python script and fix current issues with docstrings prevent sphinx from building the documentation:
The scripts/check_docstrings.py python script validates MATLAB function docstrings against the MHKiT-MATLAB
docstring template to ensure proper Sphinx documentation generation.
Docstrings are parsed by: https://github.com/sphinx-contrib/matlabdomain. This script checks for common issues that can cause Sphinx build failures or inconsistent documentation.
In this PR we also define a docstring template:
function result = descriptive_function_name(input_1, input_2, input_3)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Brief one-line description of what the function does
%
% Optional extended description paragraph. Can span multiple lines
% to provide additional context, mathematical background, data sources,
% or important behavioral notes about the function.
%
% Parameters
% ------------
% input_1 : type [units]
% Description of first parameter. Can span multiple lines.
% Additional details aligned with first line. Use two spaces for indentation
% input_1.fieldname_1 : type [units]
% Description of field
% input_1.fieldname_2 : type [units]
% Description of field
% input_2 : type [units]
% Description of second parameter
% input_t : type [units] (optional)
% Description of second parameter. Mark optional parameters
% with (optional) after the type.
%
% Returns
% ---------
% output : type
% Description of return value. For structure outputs,
% document nested fields with indentation:
% output.field1 : type [units]
% Field 1 description
% output.field2 : type [units]
% Field description
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
arguments (Input)
input_1 struct
input_2 {mustBeInteger, mustBePositive}
input_3 {mustBeInteger}
end
arguments (Output)
result struct
end
% Function implementation goes here
end
This PR also add this template and other contribution details in a new CONTRIBUTING.md
@hivanov-nrel, this is ready for review. This adds a docstring checker and defines a docstring template.
At this time it also made sense to just create a CONTRIBUTING.md with additional details on code development. Let me know if the docstring/function template makes sense, and if there is anything that makes sense to add or subtract.