GraphicDocs

Code is important, but documentation is critical. Spend more time writing code and less time agonizing over how to document it.

---

---

Table of Contents

• About
• Documenting Conventions
  • Supported Annotation Types
  • Supported Docstring Tags
• Generating Documentation
  • Building Documentation Using the Core
  • Using the Documentation Parser Independently
  • Templates
• Badge and Use in Github Projects
• License and Development

---

About

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 False

And 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 False

Nothing 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:

• Core
• Hooks
• Parser

Documenting Conventions

Python is a dynamically typed language. This means nothing in the Python compiler will prevent you from abusing data types defined through annotations.

Supported Annotation Types

GraphicDocs recognizes and supports the following annotation types for argument and return types:

• any
• bytes
• callable
• dict
• int
• False
• float
• list
• None
• set
• str
• True
• tuple

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):
    ...

Supported Docstring Tags

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.
    """

Generating Documentation

Download the project src folder and import the tool.

This project is not currently available by PIP. COMING SOON!

Building Documentation Using the Core

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.py

will output a file source.md to the working directory.

Using the Documentation Parser Independently

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)

Templates

GraphicDocs has the following template built in and available.

• Graphic_MD

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.

Badge and Use in Github Projects

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:

[![Documented with GraphicDocs](https://img.shields.io/badge/Documented%20with-GraphicDocs-841561)](https://github.com/GraphicArtQuest/GraphicDocs)

License and Development

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.