Add public function documentation script #5253
Conversation
- Currently only finds all public/invalid function files - Method "document_public" is in place to handle the data taken from a function header, but currently unimplemented
|
So, this is a bit of a weird one as I know there are some plans involving the use of http://www.sphinx-doc.org/ I've spent some time messing with that and ran into a few walls so for the time being decided to work on this python script. I've yet to look at what output format we need the data in, but am currently mulling over whether there's a better approach to splitting the header into sections than ["useless stuff", "Author", "(authors) \n (description text)", "Argument", "(arguments text)", "Return Value", "(return value text)", "Example", "(examples text)", "Public", "(public text)"] |
|
So this is basically almost finished, the only question is how we want the data to actually be output. Currently it will spit out .md files (named after component, i.e. ace_refuel_fnc_getFuelDescription Get the remaining fuel amount. Parameters
Return Value
Example [fuelTruck] call ace_refuel_fnc_getFuelAuthors
ace_refuel_fnc_makeJerryCanDescription Makes an object into a jerry can. Parameters
Return Value None Example [can] call ace_refuel_fnc_makeJerryCanAuthors
|
|
It currently just appends to the output files instead of overwriting them, but that should be solvable easily enough |
|
I see you are opening the file for each function, so you'll just have to open it with I am not sure what we want to do about removed functions though, I think we're better off just removing them from the doc anyways. Would this run on Travis? Maybe only on |
|
Yeah, just a question of how best to do the control flow for it. I guess I can just add a quick and dirty solution for now, code can all be refined later. |
|
Oh man this finally got merged? 😆 I can't remember if I wrote this with any semblance of logic, but hopefully it's in a relatively good state. Someone once contacted me on slack to ask for permission to adapt it to their project, may be worth looking into what they did if I can find who that was. |
|
Can we get this into CI too? to make sure everyone pushes valid headers? |
|
Make me a separate issue so I don't forget. |
* Remove obsolete event rename script * Add initial function documenting python script - Currently only finds all public/invalid function files - Method "document_public" is in place to handle the data taken from a function header, but currently unimplemented * Add author/description/arguments processing * Improve console logging and add return processing * Use class based approach for better data handling * Add argument processing with support for notes * Implement rudimentary doc output * Add return and example processing * Fix example variable * Fix documenting no arguments/return * Fix malformed return handling * Improve control flow
When merged this pull request will:
Current Status:
--debugargument to only check for header issuesPublicvaluePublicvalue