Ridoculous

Easily document any python object to a linked table of contents and markdown

Documentation

The documentation below was generated using Ridoculous by running the following:

import ridoculous.core
ridoculous.Ridoculous.makedocs(ridoculous.core, 'RIDOCULOUS_README.md')

• ridoculous.core
  • ridoculous.core.ClassRDoc
    • ClassRDoc.init
    • ClassRDoc.repr
    • ClassRDoc.str
  • ridoculous.core.FunctionRDoc
    • FunctionRDoc.init
    • FunctionRDoc.repr
    • FunctionRDoc.str
  • ridoculous.core.ModuleRDoc
    • ModuleRDoc.init
    • ModuleRDoc.repr
    • ModuleRDoc.str
  • ridoculous.core.RDocObject
    • RDocObject.getnewargs
    • RDocObject.new
    • RDocObject.repr
    • RDocObject._asdict
    • RDocObject._replace
  • ridoculous.core.Ridoculous
    • Ridoculous.init
    • Ridoculous.make_doc_list
    • Ridoculous.write

ridoculous.core

ridoculous.core.ClassRDoc(self, obj: object = None)

This class documents class objects. The format will look like the following for a documented class. Link is used for a table of contents and the hash of the name is used to keep the links unique.

    Table of Contents String:
        - [ name ](#link)

    Markdown string:
        <a name="[link]"></a>
        #### [name]

            [docstring]

ClassRDoc.__init__(self, obj: object = None)

When a new ClassRDoc is created, all attributes are set during init. First the obj that was passed will be verified as a class object using the inspect library. The name will be found using a regex pattern, the signature is obtained using the inspect library, the docstring is copied and then the document attributes are created. The link is created to connect the table of contents to the header, the table of contents string is then created, and lastly the markdown for the class object.

    Args:
        obj {object} -- object to document (should be a function)

ClassRDoc.__repr__(self)

overloaded for ease of use, when class is printed, it will be the str of the markdown generated for the instance of ClassRDoc

ClassRDoc.__str__(self)

overloaded for ease of use

ridoculous.core.FunctionRDoc(self, obj: object = None)

This class documents functions. The format will look like the following for a function. Link is used for a table of contents and the hash of the name is used to keep the links unique.

    Table of Contents String:
        - [ name ](#link)

    Markdown string:
        <a name="[link]"></a>
        #### [name]

            [docstring]

FunctionRDoc.__init__(self, obj: object = None)

When a new FunctionRDoc is created, all attributes are set during init. First the obj that was passed will be verified as a function using the inspect library. The name will be found using a regex pattern, the signature is obtained using the inspect library, the docstring is copied and then the document attributes are created. The link is created to connect the table of contents to the header, the table of contents string is then created, and lastly the markdown for the function.

    Args:
        obj {object} -- object to document (should be a function)

FunctionRDoc.__repr__(self) -> str

overloaded for ease of use, when class is printed, it will be the str of the markdown generated for the instance of FunctionRDoc

FunctionRDoc.__str__(self) -> str

overloaded for ease of use

ridoculous.core.ModuleRDoc(self, obj: object = None)

This class documents module objects. The format will look like the following for a module. Link is used for a table of contents and the hash of the name is used to keep the links unique.

    Table of Contents String:
        - [ name ](#link)

    Markdown string:
        <a name="[link]"></a>
        #### [name]

ModuleRDoc.__init__(self, obj: object = None)

When a new ModuleRDoc is created, all attributes are set during init. First the obj that was passed will be verified as a module using the inspect library. The name will be the __name__ of the object. The link is created to connect the table of contents to the header, the table of contents string is then created, and lastly the markdown for the module.

    Args:
        obj {object} -- object to document

ModuleRDoc.__repr__(self)

overloaded for ease of use, when class is printed, it will be the str of the markdown generated for the instance of ModuleRDoc

ModuleRDoc.__str__(self)

overloaded for ease of use

ridoculous.core.RDocObject(self, /, *args, **kwargs)

An RDocObject is a container object that is the starting object to document. The name will be taken from the initial object provided. It will then be walked to find any sub modules, classes, and functions inside the given module(s)

Args:
    name {str} -- name of RDocObject
    modules {List[ModuleRDoc]} -- list holding the documented modules

RDocObject.__getnewargs__(self)

Return self as a plain tuple. Used by copy and pickle.

RDocObject.__new__(_cls, name: str, modules: List[ridoculous.core.ModuleRDoc])

Create new instance of RDocObject(name, modules)

RDocObject.__repr__(self)

Return a nicely formatted representation string

RDocObject._asdict(self)

Return a new OrderedDict which maps field names to their values.

RDocObject._replace(_self, **kwds)

Return a new RDocObject object replacing specified fields with new values

ridoculous.core.Ridoculous(self, objects: List[object] = None)

Ridoculous - making documentation for any python object The Ridoculous class is meant to take any object and document all modules, classes, and functions found inside that object. Ridoculous relies heavily on the code being documented using docstrings that are easy to read and understand. A table of contents that links to all the found objects will be creating along with the documents that were built.

    The goal of this utility is to help document code cleanly and quickly, that will then be used inside a readme
    or document to display the information found from the objects.

Ridoculous.__init__(self, objects: List[object] = None)

The given list of objects will be parsed and ready to be documented. The list of strings that are written to the file are held in .docs. This is a raw version of what is dumped into the final output.

    Args:
        objects {List[object]} -- a list of object to document

Ridoculous.make_doc_list(self)

creates the list of markdown strings to be help in .docs. firstly iterates over the RDocObjects and creates a table of contents, lastly reiterating over the RDocObjects and ordering the markdown

    return:
        list -- a list of markdown strings to be written in a file

Ridoculous.write(self, filename: str = 'GENERATED_README.md')

write .docs to a file

    Args:
        filename {str} -- the path of the filename to save the markdown as [default: GENERATED_README.md]