Skip to main content

Generate markdown from Python sources (reST based)

Project description


Generate markdown from reST based Python docstrings

## Installation

`pip install frangidoc`

## Usage

FrangiDoc is a command line tool

### With Git

It is possible to generate markdown from a distant repository.

This repo must have a `.frangidoc.yml` file at its root, describing the modules/packages to be parsed :

It is possible to alter the environment before generation.

```yml
title: The Title
environment:
PYTHONPATH: some/path;some/other/path
SOME_ENV_VAR: some_value
modules:
- path/to/module.py
- path/to/package/__init__.py
markdown:
- path/to/markdown.md
```

```bash
python -m frangidoc git <repo_url> <output_dir>
```

Each given module will be parsed and a respective .md file will be created in the given output folder

## Syntax Examples

The following source renders as [this page](demo-output.md)

### Python source

```python
"""
Top module docstring

You can use markdown here
- A bullet
- list
- for example
"""


class OneClass(object):
"""
Class level docstring

You can use markdown here

| A | Table |
| --- | --- |
| For | Example |
"""

def __init__(self, arg_1, arg_2="default"):
"""
Constructor docstring

You can use markdown here too

:param arg_1: What is argument 1
:param arg_2: What is argument 2
"""
pass

def a_method(self, argument):
"""
Some text to describe the purpose of the method

You can use markdown here too

:param argument: What is this argument
:return: What the method returns
"""
pass

def some_function(one_param):
"""
Explain what happens here
:param one_param: Argument one **must be** something in bold
:return: None
"""
pass
```

### Markdown Output

````markdown
# Demo

Top module docstring

You can use markdown here
- A bullet
- list
- for example

## Class **OneClass**

Class level docstring

You can use markdown here

| A | Table |
| --- | --- |
| For | Example |

### Constructor

```python
OneClass(arg_1, arg_2='default')
```

Constructor docstring

You can use markdown here too


| Argument | Role |
| --- | --- |
| `arg_1` | What is argument 1 |
| `arg_2` | What is argument 2 |

### **a_method**

```python
OneClass.a_method(argument)
```

Some text to describe the purpose of the method

You can use markdown here too


| Argument | Role |
| --- | --- |
| `argument` | What is this argument |
| Returns | What the method returns |

## Functions


### **some_function**

```python
demo_doc.some_function(one_param)
```

Explain what happens here

| Argument | Role |
| --- | --- |
| `one_param` | Argument one **must be** something in bold |
| Returns | None |
````

## References

Largely inspired from

- https://medium.com/python-pandemonium/python-introspection-with-the-inspect-module-2c85d5aa5a48
- https://gist.github.com/dvirsky/30ffbd3c7d8f37d4831b30671b681c24
- https://chase-seibert.github.io/blog/2014/03/21/python-multilevel-argparse.html

Many thanks to their respective authors

Keywords: documentation markdown docstring reST
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Topic :: Software Development :: Documentation
Classifier: Operating System :: Microsoft
Classifier: Operating System :: POSIX

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
frangidoc-2.1.3.tar.gz (21.0 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page