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
Release history Release notifications | RSS feed
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)
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 018f1d886e7caad2901384c456ab016649d9f19f169520ebbbf9949ccfa4450e |
|
MD5 | d7391b1e1e3450fc7208709d77bc8624 |
|
BLAKE2b-256 | bf0b22b01a3d66b4550e00febbda4c12eb7770c993b12af03d3e2537b61904ba |