Code is important, but documentation is critical. Spend more time writing code and less time agonizing over how to document it.
Table of Contents
This project parses Python modules, classes, and functions to generate well formatted documentation.
It does this by taking advantage of several Python features defined in Python Enhancement Proposals. You do not need in depth knowledge of them to use GraphicDocs, but for more information see:
- Style Guide for Python Code (PEP 8)
- Docstring Conventions (PEP 257)
- Type Hints (PEP 484)
- Variable Annotations (PEP 526)
- Union Types (PEP 604)
It also defines a parseable docstring tagging convention (inspired by the JSDoc project for annotating Javascript code) to record information Python's built in annotations do not.
Following this convention will take a barebones example like this:
def product_is_positive(input1, input2=0):
result = input1 * input2
if result > 0:
return True
else:
return FalseAnd turn it into a much more understandable example like this:
def product_is_positive(input1: int, input2: float|int = 0) -> bool:
""" Check if the product of two numbers is positive or not.
@param input1 The first number.
@param input2 The second number.
@returns `True` if input1 and input2 multiplied together are greater than 0,
`False` otherwise or if input2 is omitted.
@throws [TypeError] If either `input1` or `input2` are not numbers.
"""
result = input1 * input2
if result > 0:
return True
else:
return FalseNothing functionally changed between the examples above, but using type hint annotations and the docstring tags made it immediately clearer about what the function does, and more importantly why.
To see some examples of what GraphicDocs can create, see its own API documentation it created on itself:
Python is a dynamically typed language. This means nothing in the Python compiler will prevent you from abusing data types defined through annotations.
GraphicDocs recognizes and supports the following annotation types for argument and return types:
anybytescallabledictintFalsefloatlistNonesetstrTruetuple
Beyond these, Python allows other entries for annotations. GraphicDocs should also work in most cases with:
- Any reference to a module (e.g.
enum), class (e.g.enum.Enum), or function (e.g.enum.unique), either built on or custom made - Any number (e.g.
0,101,-10)
You can union these together with the pipe (|) character with no limitations on what kind of types you can combine:
def myfunc(input: str|int|None|callable):
...GraphicDocs provides multiple tags that let you document things Python's annotations do not. At this time, it does not recognize foreign tags (i.e. tags not defined below).
- @author
- @copyright
- @deprecated
- @example
- @global
- @ignore
- @license
- @memberof
- @namespace
- @param
- @private
- @public
- @returns
- @since
- @throws
- @todo
- @version
Within the docstring, GraphicDocs records everything before the first tag as the description. Any carriage returns will get treated as a continuation of the same paragraph. It interprets blank lines as a new paragraph. For example:
def test_function() -> None:
""" This is the first line in the first paragraph.
This line continues as the second sentence.
This line begins a new paragraph.
@returns Nothing gets returned, and this line ends the description.
"""Download the project src folder and import the tool.
This project is not currently available by PIP. COMING SOON!
First, build a documentation generating script:
# docs.py
from graphicdocs import Core
config = {
"source": "./path/to/your/source.py"
}
core = Core(config)
core.build()Then running
python docs.pywill output a file source.md to the working directory.
You can use the individual parsing functions to get the raw dictionary object:
from graphicdocs import parse_module, parse_class, parse_function, parse_docstring
class my_class():
...
my_parsed_class = parse_class(my_class)GraphicDocs has the following template built in and available.
You can make your own templates that take the parsed data and output into whatever Markdown, HTML, or other output format you want. You can write your template locally, or build and distribute it with PIP.
I encourage you to apply the graphicdocs Github repository tag if you use this tool so others can see examples in action. Additionally, feel free to add the following badge to your repository:
[](https://github.com/GraphicArtQuest/GraphicDocs)
To help as many developers as possible, this project and all other files in this repository are distributed as free and open-source software under the MIT license, © 2022-2023.
Both contributions and bug reports welcome.
This add-on is maintained and supported. Submit a bug report if you encounter errors.
Maintained by M. Scott Lassiter.