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.

Source Distribution

frangidoc-2.1.3.tar.gz (21.0 kB view details)

Uploaded Source

File details

Details for the file frangidoc-2.1.3.tar.gz.

File metadata

  • Download URL: frangidoc-2.1.3.tar.gz
  • Upload date:
  • Size: 21.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.0

File hashes

Hashes for frangidoc-2.1.3.tar.gz
Algorithm Hash digest
SHA256 018f1d886e7caad2901384c456ab016649d9f19f169520ebbbf9949ccfa4450e
MD5 d7391b1e1e3450fc7208709d77bc8624
BLAKE2b-256 bf0b22b01a3d66b4550e00febbda4c12eb7770c993b12af03d3e2537b61904ba

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page