joaomcteixeira / hypersimpledocstring2md

A Hyper Simple Docstring to Markdown. Creates indexed Markdown files from Python libraries docstrings.

HyperSimpleDocstring2Md

A Hyper Simple Docstring to Markdown creator. Creates hierarchically indexed Markdown files from Python libraries' docstrings. Fully based on Python standard library.

Why?

It is extremely important to maintain software documentation up to date with the latest releases.

There are many packages out there to efficiently handle the documentation of Python projects, those can extract updated docstrings and setup beautiful web pages accordingly. But, such complex tools require a considerable amount of time and effort to master, and developers should thrive to keep up to date with the most novel routines and styles of documentation representation.

Moreover, in my opinion, these projects fail to address a specific collective of developers: those who thrive, above all, for extreme simplicity, long-term stability and universality of their output, in this case software documentation.

Solution

Hyper Simple Docstring 2 Markdown creator was designed to recursively extract DOCSTRINGS from a target Python package and write them to a simple yet organized and indexed Markdown formatted file. It intents to be exactly that, hyper simple in both input and output.

The output Mardown file can be directly used as a GitHub wiki page, for example.

Implementation

It uses Python +3.7 standard libraries, such as pydoc and the inspect module.

Which docstrings are covered?

In the current version, DOCSTRINGS from packages (__init__.py), modules, classes and functions are extracted.

How to use it

No installation is required and you only need to pass one argument, it's HYPER SIMPLE:

• the PATH to your Python package

python hypersimpledocstring2md.py <PATH TO YOUR LIBRARY>

This will recursively read your library and generate a docs.md file containing all referred docstrings in an organized manner. All subpackages MUST have an __init__.py file.

but there are also additional features

For example:

• you can add a base web url in order to link the index with the Markdown headers, it will result in <link>#<header>, very useful for GitHub pages.

$ python hypersimpledocstring2md.py -h
usage: hypersimpledocstring2md.py [-h] [--baselink baselink] [--output OUTPUT]
                                  path

Hyper Simple Docstring 2 Markdown - A routine to create a single Markdown
formatted file containing the documentation DOCSTRINGS of a target Python
library.

positional arguments:
  path                 PATH to Library.

optional arguments:
  -h, --help           show this help message and exit
  --baselink baselink  The base Web URL where the .md will be hosted toallow
                       Index-Header linking. Defaults to no link.
  --toplink toplink    Adds a quick link to the Index bellow each header.
                       Defaults to True.
  --output OUTPUT      The OUTPUT Markdown file. Defaults to 'docs.md'.

examples

HyperSimpleDocstring2Md is used to generate the Tauren-MD's documentation, take a look.

LICENSE

This software is licensed under the Unlicense as a demonstration of my gratitute to the whole Python community that cheerily and altruistically share knowledge on the Web. Thanks to the community.