Script Documentation... it is all in the docs
Help.... Documentation
Last thing written... if ever... First thing needed.
I have been messing with formatting my code using numpy doc strings
Code documentation.... the view on the left is within the script IDE and the view on the right is what is will look like when viewing a script's help. Fancy... fancy...
And! Not only that, your favorite Python Package Manager includes it in their python distribution so Sphinx can use it.
So here is a little 'dirr' function I wrote since dir(object) returns a messy hard to read output in any form.
Here is the documentation for the function.
def dirr(obj, colwise=True, cols=3, sub=None, prn=True):
"""A formatted dir listing of a module or function.
Source : arraytools module in tools.py, dirr def
Return a directory listing of a module's namespace or a part of it if the
`sub` option is specified. If `prn=True`, then it is simply printed. If
False, then the string is returned.
Parameters
----------
- colwise : `True` or `1`, otherwise, `False` or `0`
- cols : pick a size to suit
- sub : sub='a' all modules beginning with `a`
- prn : `True` for print or `False` to return output as string
Notes
-----
See the `inspect` module for possible additions like `isfunction`,
'ismethod`, `ismodule`
**Examples**::
dirr(art, colwise=True, cols=3, sub=None, prn=True) # all columnwise
dirr(art, colwise=True, cols=3, sub='arr', prn=True) # just the `arr`'s
(001) _arr_common arr2xyz arr_json
(002) arr_pnts arr_polygon_fc arr_polyline_fc
(003) array2raster array_fc
(004) array_struct arrays_cols
"""The key (apparently) is indentation, back-ticks and little tricks.
In Spyder's help documentation, it looks like this. ( More on Spyder as an IDE for your work )
You can produce whole documentation for your modules or even single 'scripts' to accompany your code.
And the function itself makes finding my own documentation easier
| Sample output |
|---|
|
Producing links to web links
This may be a bit much, but your documentation can also provide links to http: sites to reference specific web pages from within your documentation. Here is an example. The key is to provide a
- link number ... [1]
- a name for the link... with trailing __
- and the actual link itself.
| Web links in script documentation |
|---|
|
The **text** provides bold highlighting. The [1] on line 6, is the first link with line 7 being the link name in back-tics and trailing __. Line 9, with the leading __ is the actual link itself. What is show is a snip of the whole link list shown below.
Simpler option
You might need a simpler documentation example
References:
-----------
`<https://stackoverflow.com/questions/7352684/how-to-find-the-groups-of-
sequences-elements-from-an-array-in-numpy>`_.
`<https://stackoverflow.com/questions/50551776/python-chunk-array-on-
condition#50551924>`_.This consists of `< at the start and >`_. at the end with the link in between. This yields...
Finally
Remember, documentation is important. If not for yourself, for someone else.